Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/azahar-emu/azahar/llms.txt

Use this file to discover all available pages before exploring further.

Most problems with Azahar fall into a small set of categories. Work through the relevant section below to diagnose and fix your issue. If none of these solutions apply, check the Discord server or search the GitHub issue tracker.
A black screen after launching a game almost always points to a bad dump or a renderer mismatch.Diagnosis: The game window opens but stays black, with or without audio.
1

Verify your game dump

A corrupt or incorrectly dumped ROM will produce a black screen. Re-dump the game from your console using GodMode9 and ensure the dump completes without errors.
2

Switch the graphics backend

Open Emulation → Configure → Graphics and switch between OpenGL and Vulkan. Some games behave differently depending on the renderer.
3

Check your GPU drivers

Outdated GPU drivers can prevent the renderer from initializing. Update to the latest drivers for your GPU from the manufacturer’s website (NVIDIA, AMD, or Intel).
4

Confirm the file format is supported

Azahar supports .3ds, .cia, .cxi, .3dsx, and .elf. If your file is in a different format (e.g., .nds, .rom), it is not a 3DS game and will not load.
Encrypted ROM dumps will also cause a black screen. Make sure your dump is decrypted before loading it.
If Azahar crashes to the desktop or freezes within seconds of launching a game, check the following:Diagnosis: The emulator closes unexpectedly or stops responding right after the game starts.
1

Check your system meets the minimum requirements

  • CPU: x86-64 or ARM64, single-core Passmark score above 1,800, SSE4.2 support required on x86_64
  • GPU: OpenGL 4.3 or Vulkan 1.1 support
  • RAM: 2 GB minimum, 4 GB recommended
  • OS: Windows 10 (64-bit), macOS 13.4 (Ventura), or modern 64-bit Linux
Running Azahar on hardware below these thresholds will result in crashes or instability.
2

Switch to OpenGL if using Vulkan

Vulkan support varies across GPU models and driver versions. Open Emulation → Configure → Graphics, set the renderer to OpenGL, and try launching the game again.
3

Disable hardware shaders temporarily

In Emulation → Configure → Graphics, uncheck Use Hardware Shaders and test again. If the crash stops, try re-enabling it and updating your GPU drivers.
4

Check the log file

After a crash, open Help → Show Log or navigate to the Azahar user data folder and open the log file. The last few lines usually identify the cause. Include this file when reporting a bug.
Low frame rates are one of the most common complaints and are almost always tied to CPU performance or incorrect settings.Diagnosis: The game runs, but noticeably slower than expected — audio may also be choppy.
1

Lower the internal resolution

Navigate to Emulation → Configure → Enhancements and reduce the internal resolution to 1x (Native). Higher multipliers require significantly more GPU work.
2

Enable hardware shaders

In Emulation → Configure → Graphics, make sure Use Hardware Shaders is checked. Without hardware shaders, the CPU handles all shader computation, which is much slower.
3

Enable asynchronous shader compilation

Check Async Shader Compilation in the Graphics settings. This prevents the emulator from stalling each time a new shader is compiled.
4

Switch the graphics backend

Try switching between OpenGL and Vulkan in Emulation → Configure → Graphics. Vulkan can be faster on some hardware, slower on others.
5

Check your CPU single-core performance

3DS emulation is highly single-threaded. A CPU with a high core count but low single-core speed will struggle. Check your CPU’s single-core score at cpubenchmark.net — Azahar recommends a score above 1,800.
Closing background applications frees up CPU resources. 3DS emulation is CPU-bound, so every bit of headroom helps.
Audio issues in Azahar are usually caused by an incompatible audio backend or incorrect audio stretching settings.Diagnosis: Sound is distorted, crackling, cutting out, or completely absent.
1

Change the audio output backend

Open Emulation → Configure → Audio and change the Output Engine. Try switching between Cubeb and SDL2. Cubeb is the recommended default on most platforms, but SDL2 may be more stable on some systems.
2

Adjust audio stretching

The Audio Stretching option in Audio settings helps keep audio in sync when the emulator drops frames. If you have a fast enough system, try disabling it — on slower systems, enabling it reduces crackling.
3

Select the correct output device

If you have multiple audio devices (e.g., speakers and a headset), make sure the Output Device in the Audio settings matches the device you expect to hear sound from.
4

Enable realtime audio

Try toggling the Realtime Audio option in the Audio settings. This can improve latency on some configurations.
Some games have known audio issues at specific points. Check the compatibility list for your game to see if the issue is game-specific.
If Azahar does not respond to your controller, it usually means the controller was not connected before Azahar launched, or it has not been mapped yet.Diagnosis: Button presses have no effect, or the controller does not appear in settings.
1

Connect your controller before launching Azahar

Azahar detects controllers at startup. If you connected your controller after Azahar was already open, close Azahar, connect the controller, then relaunch.
2

Open the input configuration

Go to Emulation → Configure → Controls. Each button on the 3DS is mapped here. If all buttons show “Not Set,” your controller has not been mapped.
3

Map your controller

Click on each button field and press the corresponding button on your controller to assign it. Use the Auto Map button if your controller is a standard gamepad — Azahar will attempt to map it automatically.
4

Check the input profile

Azahar supports multiple input profiles. Make sure the correct profile is selected in the dropdown at the top of the Controls settings.
Xbox and PlayStation controllers work out of the box on most systems. Generic or less common controllers may need manual mapping.
If you added a game but it does not appear in Azahar’s game list, the issue is usually the folder configuration or an unsupported file format.Diagnosis: Your game file exists on disk but the library shows nothing, or fewer games than expected.
1

Add the correct game directory

Go to Emulation → Configure → General → Game Directories and confirm that the folder containing your game files is listed. If it is not, click Add and select the folder.
2

Check the file format

Azahar supports .3ds, .cia, .cxi, .3dsx, and .elf files. Files in any other format will not appear in the library. Confirm your file has one of these extensions.
3

Load the file directly

If you want to launch a single file without it appearing in the library, use File → Load File and select the game file directly.
4

Refresh the game list

Right-click anywhere in the game list and select Refresh (or restart Azahar) to force a rescan of configured directories.
Intermittent hitching or freezing during the first play session of a game is expected behavior, not a bug.Diagnosis: The game stutters briefly at irregular intervals, especially when entering new areas or triggering new effects, but only during the first play session.When Azahar encounters a new shader for the first time, it must compile it before rendering. This causes a brief stall. After the shader is compiled, it is saved to the disk shader cache.On subsequent play sessions, shaders load from the cache instantly, eliminating the stutter.
1

Enable the disk shader cache

In Emulation → Configure → Graphics, make sure Use Disk Shader Cache is checked. Without this, shaders are recompiled from scratch every time you launch the game.
2

Enable asynchronous shader compilation

Check Async Shader Compilation in Graphics settings. This compiles shaders in the background so gameplay is not interrupted, at the cost of brief visual glitches on first encounter.
3

Play through the game once

The stutter disappears after the shader cache is populated. You only need to experience it once per game.
Clearing the shader cache (e.g., after a driver update) will cause the stutter to return for one session.
If saving or loading a save state fails or produces an error, disk space and game load state are the most common causes.Diagnosis: Save state fails silently, produces an error, or loads a blank/corrupt state.
1

Check available disk space

Save states can be several hundred megabytes. Confirm you have sufficient free space on the drive where your Azahar user data directory is located.
2

Ensure the game is fully loaded

Save states can only be created after the game has fully initialized past its boot screen. Attempting to save during loading screens may produce a corrupt state.
3

Do not rely on save states as your only backup

Save states are tied to a specific Azahar version and game state. Use the game’s built-in save system as your primary save method, and treat save states as a convenience feature.
Save states created on one version of Azahar may not load correctly on a different version. Always keep an in-game save as a backup.
If you cannot connect to a multiplayer room, or other players cannot join your room, check firewall and version compatibility first.Diagnosis: Connection times out, room is unreachable, or players are immediately disconnected.
1

Open the required port

Azahar multiplayer uses port 24872 (UDP). If you are hosting, ensure this port is open in your firewall and, if applicable, forwarded on your router.
Port: 24872
Protocol: UDP
2

Verify game version compatibility

All players in a room must be running the same version of the game. Mismatched game versions will cause connection failures or desyncs.
3

Verify Azahar version compatibility

All players should also be on the same Azahar build. Significant version gaps can cause incompatibilities in the multiplayer protocol.
4

Check the room's region and game filter

When joining a public room, confirm the room is configured for the game you are playing. Some rooms restrict which games can be played.
Azahar multiplayer connects to community-hosted rooms, not Nintendo’s servers. Nintendo Wi-Fi features that required Nintendo’s infrastructure are not emulated.
macOS Gatekeeper blocks applications from unidentified developers by default. This is expected for apps downloaded outside the Mac App Store.Diagnosis: A dialog appears saying "Azahar.app" can't be opened because it is from an unidentified developer or similar.
1

Right-click to open

Instead of double-clicking the app, right-click (or Control-click) on Azahar.app and select Open from the context menu.
2

Confirm the override

A new dialog will appear with an Open button. Click it. macOS will remember this choice and allow the app to open normally in the future.
If the right-click method does not work, you can allow the app from System Settings → Privacy & Security, where a prompt to allow Azahar should appear after a failed launch attempt.
Azahar requires macOS 13.4 (Ventura) or later. Running it on older macOS versions is not supported and may produce launch errors unrelated to Gatekeeper.
On Linux, native Wayland mode can cause window rendering problems, crashes, or input issues. The non-Wayland build is recommended for most users.Diagnosis: Azahar fails to launch, renders incorrectly, or has input issues when running under a Wayland compositor.
1

Use the non-Wayland AppImage

If you are using the AppImage, download azahar.AppImage instead of azahar-wayland.AppImage. The default AppImage uses XWayland for compatibility and avoids upstream Wayland ecosystem issues.
2

Disable Wayland in the Flatpak build

The Flatpak build has native Wayland disabled by default. If you previously enabled it, open Flatseal, select Azahar, and remove the Wayland socket permission (wayland).Alternatively, launch the Flatpak with Wayland explicitly disabled:
WAYLAND_DISPLAY= flatpak run org.azahar_emu.Azahar
3

Enable Wayland only if required

If your system has no Xwayland support (uncommon), you may need native Wayland. Enable it in Flatseal by adding the wayland socket permission, understanding that you may encounter issues.
Most Wayland compositors support XWayland out of the box. Unless you have a specific reason to use native Wayland, the default non-Wayland build will work correctly.

Build docs developers (and LLMs) love

Get started for freeTalk to us