Reference Troubleshooting

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.

"An archive downloaded but didn't unpack"

Most archives extract automatically. The known limitation: some RAR3-compressed .rar files that use RAR's programmable filters can't be decompressed by the bundled library. For those, the raw .rar is left in the console folder and you extract it on a PC. If a specific archive won't unpack, check the debug log (Settings → View logs → View debug log) for the exact reason.

"It re-downloaded over a file I already had"

That's intended — it's how you refresh a file. When a download lands in sdmc:/roms/<console>/ and a file of the same name already exists, it's overwritten in place, with no prompt and no separate backup (a single file via a move, or, for an archive, each extracted file as it's written). The * "installed" marker in a file list is informational only — it does not block re-downloading.

It's never hidden, though:

• Logged. Every completed download is recorded in the history (downloads.log, viewable in Settings → View logs), noting when it (overwrote existing) or (overwrote N files) for an archive.
• Shown in the queue. A finished item's result column is colour-coded: (repl) orange = an existing file was replaced (with a count, e.g. (repl 12), for multi-file archives); (new) green = a brand-new file.

If you want to keep the old copy, move or rename it before downloading the new one.

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.