Skip to content

Reference Troubleshooting

Jump to bottom
digdat0 edited this page Jul 24, 2026 · 3 revisions

Common problems, roughly in the order people hit them. HaulNX is only the downloader — most "it won't play" issues are on the emulator side, so this page points you at the right fix or the right emulator page.

Downloads

A download failed or stalled.

  • Check the Queue tab — failed items can be retried there (Retry all, or per-item).
  • Restricted archive.org items need credentials. Set them via the App Utility (Export credentials.json) or in-app, and confirm the item is one your account can access.
  • If the whole app can't reach the network, the queue shows a waiting-for-network banner and resumes on its own once you're back online.

A download resumed as a re-download after a restart.

  • Partly-downloaded archives resume at extraction on the next launch; a fresh start re-checks the .part file. If it re-downloads, the partial was incomplete or its target folder changed.

"I downloaded a game but the emulator doesn't see it"

This is the most common one, and it's almost always one of three things:

  1. It's still zipped. Disc-based systems (psx, saturn, dc, sega-cd, pc-engine-cd) and several standalone emulators (melonDS, Raikopon, Dekopon) want the extracted file, not a .zip. Cartridge systems in RetroArch are the exception — they read straight from .zip, as does DraStic for DS. See the emulator's page.
  2. The emulator hasn't scanned the folder. RetroArch builds playlists by scanning — rescan sd:/roms after every HaulNX session (playlists don't watch the filesystem). Standalone emulators need the /roms/<console> folder added to their content list.
  3. Wrong folder. Confirm the game actually landed in sd:/roms/<console>/ for the system you expect — the folder-name table lists every slug.

"The emulator itself crashes the moment I open it"

If it's NetherSX2, DraStic, or Cemu, this is almost certainly the launch mode rather than a bad download. All three need the full memory of a game override and won't run in applet/album mode — the way most homebrew is normally started.

Hold R while opening an installed game from the Switch home menu, and launch the emulator from the homebrew menu that appears. Each of those apps can also install a forwarder that does this for you. Nothing else on this wiki needs it.

"It boots to a black screen / won't start"

  • Missing or wrong BIOS. CD systems and a few others need console firmware — see BIOS Files. Wrong filename or wrong region is the usual culprit.
  • Wrong disc file loaded. For .cue+.bin games, open the .cue, not the .bin. See Disc Images.
  • Arcade romset mismatch. MAME and pFBN need a romset version that matches the emulator build — mismatched sets throw checksum errors.

"It runs, but too slowly"

  • Overclock. N64, Saturn, Dreamcast, PSP, DS, 3DS, PS2, and Wii U lean on it heavily — see Overclocking. Dock the console for the demanding ones.
  • First run of a Cemu game is always the worst — shaders compile as you play and cache afterwards. Give it a second session before judging.
  • Temper expectations by system. The Switch is great through the 16/32-bit generations, PS1, Dreamcast, PSP, and handhelds. N64/Saturn/DS/3DS are game-dependent, PS2 via NetherSX2 works for lighter titles only, and Wii U via Cemu is brand new and varies wildly by game. GameCube/Wii don't realistically run — see Experimental.
  • Turn off enhancements (upscaling, texture filtering, widescreen) if you enabled them — they cost performance.

"My save disappeared"

  • Many emulators write the save (.sav, memory cards, VMU) next to the ROM in sd:/roms/<console>/. Deleting a game's files from the library also deletes its save. Back up saves before cleaning house. DuckStation/Flycast/others keep some saves in their own folders instead — check the emulator page.

"Multi-disc game won't let me swap discs"

  • Load an .m3u playlist that lists all discs, not an individual disc — then use the emulator's in-menu disc-swap. Full walkthrough on Disc Images & Multi-Disc Games.

Still stuck

  • Each emulator's own site (linked at the top of its page) is authoritative for its quirks.
  • For HaulNX itself, open an issue with what you downloaded, where it landed, and which emulator you pointed at it.

Clone this wiki locally