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, Dekopon) want the extracted file, not a .zip. Cartridge systems in RetroArch are the exception — they read straight from .zip. 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.

"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, and 3DS lean on it heavily — see Overclocking. Dock the console for the demanding ones.
• Temper expectations by system. The Switch is great through the 16/32-bit generations, PS1, Dreamcast, PSP, and handhelds. N64/Saturn/DS are game-dependent. GameCube/Wii/PS2 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.