Troubleshooting

This guide helps you diagnose and fix common problems with Hydra Nintendo Switch emulator.

Quick Diagnostics

Before diving into specific issues, run through this checklist:

Check Logs

Logs are your first source of diagnostic information.Log location:

macOS: ~/Library/Logs/Hydra/
Linux: ~/.config/Hydra/logs/
Windows: %APPDATA%/Hydra/logs/

Look for ERROR or FATAL messages.

Verify Configuration

Open Settings (⌘+,) and check:

✅ Firmware path is set and valid
✅ Game paths contain games
✅ CPU/GPU settings are appropriate
✅ Log output is not set to “none”

Test with Different Game

Try loading a different game to determine if the issue is:

Game-specific (one game fails)
System-wide (all games fail)

Check System Resources

Monitor:

CPU usage (should be high during emulation)
Memory usage (games can use several GB)
Disk space (ensure sufficient free space)

Common Issues

Hydra won't launch

Symptoms

Application crashes immediately on launch
Window doesn’t appear
Dock icon bounces and disappears

Solutions

1. Check macOS version

Hydra requires macOS 11.0 (Big Sur) or later
Verify: Apple menu > About This Mac

2. Reset configuration

# Backup current config
mv ~/Library/Application\ Support/Hydra/config.toml ~/Desktop/config.toml.backup

# Launch Hydra (creates new default config)

3. Check console for errors

# Run from terminal to see crash logs
open -a Hydra
# Watch Console.app for errors

4. Reinstall Hydra

Delete app from Applications
Empty Trash
Redownload and install

Game won't load

Symptoms

Game appears in library but won’t start
Black screen when launching
Immediate crash after selecting game

Diagnostics

Check log file for:

ERROR: Failed to load game
FATAL: Missing firmware
ERROR: Invalid NCA file

Solutions by Cause

Missing Firmware
Corrupted Game File
Unsupported Format

Error indicates: Font files or system archives not foundFix:

Verify firmware path: Settings > System > Firmware Path
Ensure firmware directory contains .nca files
Check for required files:
- 0100000000000811.nca (FontStandard)
- 0100000000000810.nca (FontNintendoExtension)

See Firmware Guide for detailed instructions.

Error indicates: File format not recognizedFix:

Verify file extension is .nro or .nca
Check if game requires loader plugin
Ensure file is actually a Switch game (not 3DS, etc.)

Graphics issues

Black Screen

Possible causes:

Shader compilation failure
GPU driver issue
Incompatible shader backend

Solutions:

Switch to MSL shader backend
- Settings > Graphics > Shader backend > MSL
- Restart Hydra
Check display resolution
- Settings > Graphics > Display resolution
- Try “Auto” or “720p”

Verify Metal support

# Check GPU info
system_profiler SPDisplaysDataType

Ensure Metal is supported

AIR shader backend is currently broken. Always use MSL.

Graphical Glitches

Symptoms:

Corrupted textures
Flickering objects
Missing graphics
Wrong colors

Try:

Lower resolution to 1080p or 720p
Capture GPU frame for debugging (⌘+P)
Check log for shader errors
Update macOS to latest version
Reset shader cache (delete and restart)

Performance Issues

Symptoms:

Low FPS (frames per second)
Stuttering
Audio crackling

Optimization steps:

Use Apple Hypervisor

Settings > CPU > CPU backend > Apple HypervisorProvides best performance on macOS.

Lower Resolution

Settings > Graphics > Display resolution > 720pHigher resolutions require more GPU power.

Close Other Apps

Free up CPU and memory by closing:

Web browsers with many tabs
Video editing software
Other games or emulators

Monitor Resources

Open Activity Monitor:

Check CPU usage per core
Verify sufficient free RAM
Look for competing processes

Audio problems

No Audio

Check:

Audio backend: Settings > Audio > Audio backend
Should be “Cubeb” (not “Null”)
macOS system volume is not muted
Output device is correct

Fix:

# In config.toml
[Audio]
backend = "Cubeb"  # Not "Null"

Audio Crackling/Stuttering

Causes:

CPU bottleneck (can’t maintain frame rate)
Audio buffer underruns
Background processes interfering

Solutions:

Follow performance optimization steps above
Close audio-intensive apps (music players, DAWs)
Check CPU usage in Activity Monitor
Try disabling audio temporarily to test:
```
[Audio]
backend = "Null"
```

Controls not working

Keyboard Input Issues

Check:

Hydra window has focus (click on it)
You’re in-game (not in a menu)
Using supported keys (see Controls)

Debug:

Test with different keys
Try arrow keys for D-pad
Check if ANY keys work
Verify keyboard works in other apps

Controller Not Detected

Troubleshooting steps:

Verify Connection

Check Bluetooth or USB connection
Controller should appear in System Settings > Bluetooth
Try reconnecting

Test in macOS

Open a game that supports controllers to verify it works system-wide

Restart Hydra

Controllers should be connected BEFORE launching Hydra

Connect controller
Launch Hydra
Load game

Check Compatibility

Verify controller is supported:

PlayStation DualShock 4/DualSense
Xbox One/Series controllers
Nintendo Pro Controller
MFi certified controllers

Save data issues

Save Not Loading

Check:

Save path: Settings > System > Save Path
Save file exists: {save_path}/{title_id}/{user_id}/
User ID matches
File permissions (should be readable/writable)

Save Corruption

Symptoms:

Game says “corrupted save data”
Progress lost
Cannot load save

Recovery:

Check for backup saves (macOS Time Machine)
Try different user profile
Look in save directory for .bak files
May need to start new save

Prevention:

# Regular backups
cp -r ~/Library/Application\ Support/Hydra/save ~/Desktop/save_backup_$(date +%Y%m%d)

Crashes and instability

Random Crashes

Gather information:

Check log file timestamp matching crash
Note what you were doing when it crashed
Check macOS Console.app for crash reports

Common causes:

Segmentation Fault
Out of Memory
GPU Errors

Error: SIGSEGV or segfault in logsCause: Invalid memory accessTry:

Enable recovery: Settings > Debug > Recover from segfault
```
[Debug]
recover_from_segfault = true
```
Check if specific game or game action triggers it
Report with log file

Recovery mode is experimental and may cause data corruption.

Freezing

If Hydra becomes unresponsive:

Force quit:
- Option + Command + Esc
- Select Hydra
- Click Force Quit
Check logs before restarting to see what caused freeze
Common causes:
- Infinite loop in emulated code
- Deadlock in threading
- GPU hang

Debug Settings

For troubleshooting, enable enhanced logging:

Enable Debug Logging

Settings > Debug:

[Debug]
log_output = "file"          # Save to log file
log_fs_access = true          # Log filesystem operations
debug_logging = true          # Verbose debug messages

Debug logging generates large log files and may impact performance. Disable when not needed.

Log File Analysis

Key log levels:

INFO - Normal operation
WARN - Potential issues (yellow flags)
ERROR - Problems that may affect functionality
FATAL - Critical errors causing crashes

Search for:

ERROR:
FATAL:
Failed to
Cannot find
Assert failed

GDB Debugging

For developers debugging emulated code:

[Debug]
gdb_enabled = true
gdb_port = 1234
gdb_wait_for_client = false

Connect with:

gdb
(gdb) target remote localhost:1234

GDB debugging is for emulator development, not regular use.

Debugger View

Hydra includes a built-in debugger:

Accessing Debugger

Enable debug settings
Launch a game
Open debugger window (if available)

Debugger Features

Thread list - View emulated threads
Thread status - Running, paused, crashed
Messages - Debug messages from emulated code
Stack traces - Call stacks for crashes
Break reasons - Why thread stopped

Interpreting Messages

[LogLevel] [Class] Message
File: source_file.cpp:123
Function: function_name()

Log Classes:

Horizon - Nintendo Switch OS layer
Kernel - Kernel operations
Common - General emulator
GPU - Graphics
Audio - Audio system
Input - Input handling

Getting Help

Before Reporting Issues

Reproduce the Problem

Ensure the issue happens consistently:

Try multiple times
Note exact steps to reproduce
Test with different games if applicable

Gather Information

Collect:

Hydra version
macOS version
Mac model (Apple Silicon or Intel)
Game name and format
Log file showing the error
Screenshots/video if relevant

Check Existing Issues

Search for similar problems:

GitHub issues
Community forums
Documentation

Provide Clear Description

When reporting:

✅ Steps to reproduce
✅ Expected vs actual behavior
✅ Relevant log excerpts
✅ System information
❌ “It doesn’t work”
❌ Screenshots of text (paste text instead)

Log File Submission

When sharing logs:

Use a paste service (GitHub Gist, Pastebin)
Include timestamp of when issue occurred
Trim to relevant section (before/during/after error)
Remove sensitive information (usernames, paths if needed)

Good log excerpt:

[2024-03-03 12:34:56] INFO  Hydra: Loading game: Example Game
[2024-03-03 12:34:57] ERROR GPU: Shader compilation failed
[2024-03-03 12:34:57] ERROR GPU: Invalid MSL source
[2024-03-03 12:34:57] FATAL Hydra: Failed to initialize renderer

Advanced Troubleshooting

Clean Reinstall

For persistent issues:

# 1. Backup important data
cp -r ~/Library/Application\ Support/Hydra ~/Desktop/Hydra_backup

# 2. Remove all Hydra data
rm -rf ~/Library/Application\ Support/Hydra
rm -rf ~/Library/Logs/Hydra
rm -rf ~/Library/Caches/Hydra

# 3. Delete application
rm -rf /Applications/Hydra.app

# 4. Reinstall Hydra

# 5. Restore only config if needed
cp ~/Desktop/Hydra_backup/config.toml ~/Library/Application\ Support/Hydra/

Diagnosing Metal Issues

Check Metal support:

system_profiler SPDisplaysDataType | grep -i metal

Should show: Metal: Supported or Metal Family: ...

File System Debugging

Enable filesystem logging:

[Debug]
log_fs_access = true

Shows all file operations in log:

FS: Open /firmware/FontStandard
FS: Read 1024 bytes from offset 0
FS: File not found: /save/0100..../user.dat

Useful for diagnosing:

Missing files
Permission errors
Path issues

Performance Profiling

Monitor performance:

FPS counter - Check frame time average
Activity Monitor - CPU per-core usage
GPU History - GPU utilization
Temperature - Check for thermal throttling

Ideal performance:

60 FPS for most games
High CPU usage on 1-2 cores
Moderate GPU usage
Stable frame times

Known Issues

AIR Shader BackendThe AIR (Apple Intermediate Representation) shader backend is currently non-functional. Always use MSL.

Number KeysNumber key support for keyboard input is not yet implemented.

Still Need Help?

If you’ve tried everything:

Review this guide thoroughly
Check Configuration for settings issues
Read Firmware if firmware-related
Search existing issues on GitHub
Ask in community forums with full details
Report a bug with reproduction steps and logs

Provide:

Hydra version
macOS version
Hardware (Apple Silicon / Intel)
Full log file
Exact steps to reproduce
What you’ve already tried

Get Started

User Guide

Features

Resources

​Quick Diagnostics

​Common Issues

​Symptoms

​Solutions

​Symptoms

​Diagnostics

​Solutions by Cause

​Black Screen

​Graphical Glitches

​Performance Issues

​No Audio

​Audio Crackling/Stuttering

​Keyboard Input Issues

​Controller Not Detected

​Save Not Loading

​Save Corruption

​Random Crashes

​Freezing

​Debug Settings

​Enable Debug Logging

​Log File Analysis

​GDB Debugging

​Debugger View

​Accessing Debugger

​Debugger Features

​Interpreting Messages

​Getting Help

​Before Reporting Issues

​Log File Submission

​Advanced Troubleshooting

​Clean Reinstall

​Diagnosing Metal Issues

​File System Debugging

​Performance Profiling

​Known Issues

​Still Need Help?

Build docs developers (and LLMs) love

Quick Diagnostics

Common Issues

Symptoms

Solutions

Symptoms

Diagnostics

Solutions by Cause

Black Screen

Graphical Glitches

Performance Issues

No Audio

Audio Crackling/Stuttering

Keyboard Input Issues

Controller Not Detected

Save Not Loading

Save Corruption

Random Crashes

Freezing

Debug Settings

Enable Debug Logging

Log File Analysis

GDB Debugging

Debugger View

Accessing Debugger

Debugger Features

Interpreting Messages

Getting Help

Before Reporting Issues

Log File Submission

Advanced Troubleshooting

Clean Reinstall

Diagnosing Metal Issues

File System Debugging

Performance Profiling

Known Issues

Still Need Help?