Skip to main content
This guide helps you diagnose and resolve common issues when using Ryujinx. Follow these troubleshooting steps to get your games running smoothly.

​
System Requirements

Before troubleshooting, verify your system meets the minimum requirements:

RAM

Minimum: 8GBInsufficient RAM is a common cause of crashes and poor performance.

Graphics

OpenGL 4.5+ or Vulkan 1.2+Update graphics drivers to the latest version.

CPU

64-bit CPUModern multi-core CPU recommended for best performance.

Operating System

Windows 10/11, Linux, or macOSKeep your OS updated to the latest version.

​
Log Files

Log files are essential for diagnosing issues:

​
Locating Log Files

Default Location:
%APPDATA%\Ryujinx\Logs\
Or from Ryujinx executable directory:
<RyujinxInstallDir>\Logs\
Quick Access:
  1. Press Win + R
  2. Type %APPDATA%\Ryujinx\Logs
  3. Press Enter

​
Enabling Detailed Logging

For better diagnostics, enable additional logging:
1

Open Logging Settings

Navigate to File > Settings > Logging
2

Enable Log Levels

Enable these log levels:
"LoggingEnableDebug": true,
"LoggingEnableStub": true,
"LoggingEnableInfo": true,
"LoggingEnableWarn": true,
"LoggingEnableError": true
Trace logging provides even more detail but impacts performance:
"LoggingEnableTrace": true
3

Enable File Logging

Ensure file logging is enabled:
"LoggingEnableFileLog": true
4

Reproduce the Issue

  • Save settings and restart Ryujinx
  • Reproduce the problem
  • Check the latest log file for error messages

​
Reading Log Files

Log files are named by timestamp: 
Ryujinx_2026_03_10_14_30_25.log
Look for lines containing:
  • ERROR - Critical errors
  • WARN - Warnings that may indicate issues
  • STUB - Unimplemented features being used

​
Common Issues

​
Startup and Installation Issues

Solutions:
  1. Check for missing dependencies:
    • Windows: Install .NET 8.0 Runtime
    • Linux: Install .NET 8.0 via package manager
    • macOS: .NET is bundled with Ryujinx
  2. Verify system requirements:
    • 64-bit operating system
    • Minimum 8GB RAM
    • OpenGL 4.5+ or Vulkan 1.2+ support
  3. Run as administrator (Windows):
    • Right-click Ryujinx.exe
    • Select “Run as administrator”
  4. Check antivirus/firewall:
    • Add Ryujinx to antivirus exceptions
    • Temporarily disable to test
  5. Delete configuration and restart:
    • Backup and delete Config.json
    • Ryujinx will create a new default config
  6. Check logs for specific errors:
    • Look in Logs folder for recent log files
    • Search for ERROR or EXCEPTION messages
Causes:
  • Outdated graphics drivers
  • Unsupported graphics backend
  • GPU doesn’t meet requirements
Solutions:
  1. Update graphics drivers:
    • NVIDIA: GeForce Experience or nvidia.com
    • AMD: Radeon Software or amd.com
    • Intel: Intel Driver & Support Assistant
  2. Try different graphics backend:
    • Edit Config.json
    • Change "GraphicsBackend" from "Vulkan" to "OpenGl" (or vice versa)
    • Restart Ryujinx
  3. Verify GPU capabilities:
    • Windows: Run dxdiag and check GPU
    • Linux: Run glxinfo | grep OpenGL or vulkaninfo
    • macOS: About This Mac > Graphics
  4. On multi-GPU systems:
    • Force Ryujinx to use dedicated GPU
    • Windows: Graphics Settings > Add Ryujinx > High Performance

​
Game-Specific Issues

Diagnostic steps:
  1. Verify game file integrity:
    • Check if file is complete and not corrupted
    • Try loading a different game to test emulator
  2. Check firmware and keys:
    • Ensure latest firmware is installed
    • Verify prod.keys is present and valid
  3. Enable file integrity checks: 
    "EnableFsIntegrityChecks": true
  4. Try different graphics backend:
    • Switch between Vulkan and OpenGL
    • Some games work better with specific backends
  5. Check game compatibility:
    • Not all games are fully compatible
    • Check compatibility list or community forums
  6. Review logs:
    • Look for “Missing service” errors
    • Check for decryption failures
    • Note any ERROR messages
Common causes and solutions:
  1. Insufficient RAM:
    • Close other applications
    • Upgrade to 16GB RAM if possible
    • Don’t use 6GB or 8GB DRAM expansion unless needed
  2. Graphics driver crash:
    • Update to latest GPU drivers
    • Reduce graphics settings (resolution scale, AA)
    • Try different graphics backend
  3. Shader compilation issues:
    • Enable shader cache if disabled
    • Delete shader cache and rebuild: 
      <RyujinxFolder>/games/<TitleID>/cache/
  4. Mods causing issues:
    • Disable all mods in Mod Manager
    • Test game without mods
    • Re-enable mods one by one to find culprit
  5. Game-specific bugs:
    • Check if known issue
    • Try different game version/update
    • Report on GitHub if reproducible
Performance optimization:
  1. Enable PPTC (Profiled Persistent Translation Cache): 
    "EnablePtc": true
    • Requires 2-3 launches to build cache
    • Dramatically improves load times and stability
  2. Reduce graphics settings:
    • Resolution Scale: 1x or 2x
    • Anti-Aliasing: None
    • Disable texture recompression
    • Use Bilinear scaling filter
  3. Optimize backend:
    • Use Vulkan for best performance (if supported)
    • Enable shader cache
    • Set Backend Threading to Auto
  4. System optimization:
    • Close background applications
    • Disable browser, Discord, streaming software
    • Set Windows power plan to High Performance
    • Update all drivers
  5. Memory manager mode: 
    "MemoryManagerMode": "HostMappedUnsafe"
    • Default and fastest option
    • Try “HostMapped” if experiencing crashes
  6. CPU turbo multiplier:
    • Don’t change unless you know what you’re doing
    • Values over 100% speed up emulation but can break games

​
Graphics Issues

Solutions:
  1. Clear shader cache:
    • Navigate to <RyujinxFolder>/games/<TitleID>/cache/
    • Delete shader cache files
    • Restart game (cache will rebuild)
  2. Try different graphics backend:
    • Vulkan → OpenGL or vice versa
    • Different backends handle some effects differently
  3. Update GPU drivers:
    • Critical for graphics stability
    • Use clean installation if available
  4. Adjust graphics settings:
    • Disable texture recompression
    • Change anti-aliasing method
    • Try different scaling filter
  5. Check for overheating:
    • Monitor GPU temperature
    • Clean dust from cooling system
    • Reduce overclock if applicable
  6. Macro HLE setting: 
    "EnableMacroHLE": true
    • Try toggling this setting
    • Some games have issues with it enabled/disabled
Solutions:
  1. VSync mode: 
    "VSyncMode": "Switch"
    • Use “Switch” mode for proper frame pacing
    • Avoid “Unbounded” unless using VRR display
  2. Force VSync in GPU driver:
    • NVIDIA Control Panel: Manage 3D Settings
    • AMD Radeon Settings: Gaming > Global Settings
    • Force VSync on for Ryujinx
  3. Window vs Fullscreen:
    • Try switching between windowed and fullscreen
    • Some setups have better VSync in one mode
  4. Enable FreeSync/G-Sync:
    • If you have compatible monitor
    • May allow using Unbounded VSync without tearing

​
Audio Issues

For detailed audio troubleshooting, see the Audio Settings guide.Quick fixes:
  1. Change audio backend:
    • Try SDL3, OpenAL, or SoundIo
    • SDL3 is usually most reliable
  2. Check volume:
    • Ryujinx volume slider (Settings > Audio)
    • System volume mixer
    • In-game audio settings
  3. Audio driver updates:
    • Update audio drivers (especially Realtek)
    • Update motherboard chipset drivers
  4. Disable audio enhancements:
    • Windows: Sound Settings > Device Properties > Disable all enhancements

​
Input Issues

For detailed input troubleshooting, see the Input Configuration guide.Quick solutions:
  1. Connect controller before starting Ryujinx:
    • Ryujinx detects controllers on startup
    • Reconnect and restart if controller was connected later
  2. Reconfigure input:
    • Settings > Input
    • Remove and re-add controller
    • Remap all buttons
  3. Check controller in other applications:
    • Verify controller works in other games
    • Test with gamepad tester tools
  4. USB vs Bluetooth:
    • Try wired USB connection
    • Bluetooth can have latency/reliability issues
  5. Update controller firmware:
    • Check manufacturer’s website for updates
    • Xbox controllers: Xbox Accessories app
    • PS controllers: PC/Steam firmware updates

​
Advanced Troubleshooting

​
Per-Game Configuration

Some games require specific settings:
1

Access Game Settings

Right-click game > Manage User Configuration
2

Try These Settings

For problematic games:Graphics:
  • Resolution Scale: 1x
  • Backend: Try both Vulkan and OpenGL
  • Disable texture recompression
System:
  • DRAM Size: 4GB (default)
  • Memory Manager: HostMappedUnsafe
  • Docked Mode: Try both on and off
Audio:
  • Try different backends
3

Test Changes

Launch game and test if issues are resolved

​
Configuration Reset

If Ryujinx becomes unstable:
Before resetting:
  • Backup Config.json
  • Note your current settings
  • Save data is not affected by config reset
1

Full Reset via GUI

  1. File > Settings
  2. Click Reset button (bottom-left)
  3. Confirm reset
  4. Ryujinx restarts with default settings
2

Manual Reset

  1. Close Ryujinx completely
  2. Navigate to Ryujinx folder
  3. Rename or delete Config.json
  4. Restart Ryujinx (new config is created)

​
Clean Installation

For persistent issues, perform a clean installation:
1

Backup Important Data

Backup these folders:
  • games/ - Save data and per-game configs
  • profiles/ - User profiles
  • system/ - Keys and firmware
2

Uninstall Ryujinx

  • Delete Ryujinx installation folder
  • Delete Ryujinx data folder:
    • Windows: %APPDATA%\Ryujinx
    • Linux: ~/.config/Ryujinx
    • macOS: ~/Library/Application Support/Ryujinx
3

Reinstall Ryujinx

  • Download latest version
  • Extract to new location
  • Run Ryujinx
4

Restore Data

  • Copy backed-up folders to new Ryujinx folder
  • Do NOT restore Config.json - let Ryujinx create a fresh one
  • Reconfigure settings manually

​
Debug Mode

For developers or advanced troubleshooting:

​
Enable Debug Features

"LoggingEnableDebug": true,
"LoggingEnableTrace": true,
"LoggingGraphicsDebugLevel": "All"
Debug logging significantly impacts performance. Only enable when needed for troubleshooting.

​
GDB Stub (Developers)

For debugging game code: 
"EnableGdbStub": true,
"GdbStubPort": 55555,
"DebuggerSuspendOnStart": false
Connect debugger to localhost:55555.

​
Getting Help

​
Before Asking for Help

1

Search Existing Resources

  • Check this documentation
  • Search GitHub issues
  • Look through Discord/community forums
2

Gather Information

Collect:
  • Ryujinx version
  • Operating system and version
  • CPU and GPU models
  • RAM amount
  • Graphics backend being used
  • Game Title ID and version
  • Log files showing the issue
3

Try Basic Troubleshooting

  • Update Ryujinx to latest version
  • Update GPU drivers
  • Try different graphics backend
  • Test with default settings
  • Check logs for obvious errors

​
Where to Get Help

GitHub Issues

Report bugs and technical issues

Discord Community

Community support and discussion

Documentation

Check other guides in this documentation

Wiki

Official Ryujinx wiki

​
Reporting Bugs

When reporting issues on GitHub:
  1. Search for existing issues first
  2. Use the issue template
  3. Provide complete information:
    • System specifications
    • Ryujinx version
    • Game details (Title ID, version)
    • Steps to reproduce
    • Log files (attach or paste relevant sections)
    • Screenshots/videos if applicable
  4. Be descriptive and patient

​
Error Code Reference

Common error codes and their meanings:
Meaning: Game is calling a Switch system service that Ryujinx hasn’t implementedSolutions:
  • Usually not critical - game may still work
  • Check if setting "IgnoreMissingServices": true helps
  • Report to developers if game is unplayable
Meaning: Missing or incorrect encryption keysSolutions:
  • Install proper prod.keys file
  • Ensure keys match firmware version
  • Verify game files are not corrupted
Meaning: System ran out of available RAMSolutions:
  • Close other applications
  • Ensure you have minimum 8GB RAM
  • Don’t use 6GB or 8GB DRAM expansion
  • Lower graphics settings
Meaning: GPU driver couldn’t compile game shadersSolutions:
  • Update GPU drivers
  • Clear shader cache and rebuild
  • Try different graphics backend
  • Check GPU supports required OpenGL/Vulkan version

​
Next Steps

Configuration

Review configuration options

Graphics Settings

Optimize graphics settings

Audio Settings

Configure audio backend

Game Loading

Learn about game file formats

Build docs developers (and LLMs) love

Get started for freeTalk to us