Skip to content

Troubleshooting🔗

Most NextUI problems come down to one of these areas:

  • SD card formatting or file placement;
  • missing ROMs or wrong folder tags;
  • missing BIOS files;
  • arcade ROM sets that do not match the emulator;
  • community Paks that are missing, outdated, or not built for your device;
  • hidden .userdata settings or save states.

Start with the symptom that matches your problem.

The device boots stock OS instead of NextUI🔗

Check:

  1. The SD card uses Master Boot Record (MBR), not GPT.
  2. The card is FAT32 or exFAT.
  3. MinUI.zip is on the SD-card root and is still zipped.
  4. The trimui/ folder from the release is on the SD-card root.
  5. You did not copy the release folder one level too deep.
  6. The SD card was safely ejected after copying files.
  7. Try a different SD card if settings are not saving or files keep corrupting.

Good root layout:

SDCARD_ROOT/
├── Bios/
├── MinUI.zip
├── Overlays/
├── README.txt
├── Roms/
├── Saves/
├── Shaders/
├── nextui.pak_store.pakz
├── nextui.updater.pakz
├── nextui.upgrade_bluez.tg5040.pakz
└── trimui/

Bad root layout:

SDCARD_ROOT/
└── NextUI-v6.10.0-base/
    ├── MinUI.zip
    └── trimui/

The menu only shows Tools🔗

NextUI only shows systems that have visible games unless empty systems are enabled.

Check:

  1. Roms/ exists at the SD-card root.
  2. Your ROMs are inside system folders under Roms/.
  3. The system folder has a valid tag in parentheses, such as Game Boy (GB).
  4. At least one supported ROM file is inside the folder.
  5. If you intentionally want to manage empty systems, enable the setting that shows empty consoles.

Example:

Roms/Game Boy (GB)/Tetris (World).gb

A system folder does not appear🔗

Check:

  • The folder is inside Roms/.
  • The folder tag matches an installed emulator Pak.
  • The ROM extension is supported by that emulator.
  • The emulator is installed if it is an optional/community Pak.
  • You did not disable or hide the system in menu settings.

For arcade and Neo Geo, use (FBN) unless maintainers document another supported Pak.

A game appears but returns to the menu🔗

Check:

  1. Does that system require a BIOS file?
  2. Does the ROM match the emulator?
  3. If it is arcade/Neo Geo, is it an FBNeo-compatible ROM set?
  4. If it is a community Pak or PortMaster game, see Pak Troubleshooting and PortMaster.
  5. Update NextUI.
  6. Check logs.

For community Paks, PortMaster, and standalone emulators, do not assume built-in save/resume/menu behavior applies.

Logs are in hidden platform folders:

SDCARD_ROOT/.userdata/<platform>/logs/

For built-in emulator Paks, logs use the emulator tag:

.userdata/tg5040/logs/FBN.txt
.userdata/tg5050/logs/PS.txt

Wi-Fi password keeps asking again🔗

First check that the password is correct. A wrong Wi-Fi password should not be saved.

If the password is definitely correct but NextUI keeps forgetting it, especially together with other symptoms such as boot problems or settings not saving, suspect SD-card write problems.

Try:

  • safely ejecting the card and trying again;
  • checking the card for filesystem errors;
  • using a simpler Wi-Fi password temporarily to rule out unusual characters;
  • trying another SD card.

Files disappeared or the computer says the card must be formatted🔗

Stop writing to the card and make a backup if possible.

On Windows, chkdsk may be able to repair filesystem errors:

chkdsk X: /f /r

Replace X: with the SD-card drive letter.

Warning

Filesystem repair can recover a card, but it is not a substitute for backups. If corruption repeats, replace the SD card.

Save states crash after importing🔗

Use in-game saves when moving between systems. Save states are emulator snapshots and often fail across different cores, different emulator versions, or different save-state formats.

If you imported a RetroArch .state.auto or .state1 file and it appears but crashes, it may not be compatible with NextUI's current core.

Before asking for help🔗

Include this information:

Device:
NextUI version:
Stock firmware version, if known:
SD card brand/size:
FAT32 or exFAT:
MBR or GPT:
Fresh install or update:
Exact path of the file:
Exact filename:
What you expected:
What happened instead:
Log file, if available:

For ROM problems, include the folder path and filename. For arcade problems, include the exact ZIP filename but do not share copyrighted ROM files.