Skip to content
NxNative

Troubleshooting

Most problems with nxnative have a known cause. Find yours below. If none fits, check the game's notes from its game page, then report it on nxnative's GitHub issues with the app's log. Problems with a Launcher go to that Launcher's own page.

Your own keys and games only. NxNative cannot help with obtaining keys or game files and never explains how.

Short stutters the first time

Brief stutters the first time a new scene appears are normal. The app compiles the graphics for that scene once and remembers them, so the next time it runs smoothly. On later launches, what it remembered is prepared before the game starts, behind a "Preparing shaders" progress bar.

The very first start of a game, or the first after an update with new shaders, may wait a few minutes on a "Preparing pipelines" screen. That is the Pipeline prebuild setting doing its work up front, once. You can turn it off to skip the wait, at the cost of more brief stalls while playing. See Settings.

The game crashes or closes

  • Turn on the increased memory limit. Without it, iOS closes the bigger games. If your sideloading tool offers it, turn it on and install again. See Sideloading.
  • Try turning off Metal 4 pipelines. nxnative suggests this only when a game crashes or runs out of memory with it on.
  • Reset to tested defaults on the settings screen, in case a changed setting is the cause.
  • Turn off motion if crashes or odd behaviour involve motion controls: DM_MOTION=0 in Documents/env.txt, or pack with --no-motion. See Controllers.
  • Check that the game is on the list. Only tested games are supported. For other games the script guesses the settings, and the app may not start.

Where the log is

When something goes wrong, the log is what helps. Send it with any bug report.

  • iPhone and iPad: in the Files app, under the game's name: log.txt, with the previous run in log.prev.txt.
  • Mac: ~/Library/Logs/nxnative/<title ID>.log, with the previous run in <title ID>.prev.log.

My saves are gone after reinstalling

Some sideloading tools give a reinstalled app a new data folder, so the game starts fresh. Your progress is still in the old folder. In the Files app, copy save/ and pso_user.tsv from the old folder into the new one.

Two more things to know:

  • Install updates of a game with the same bundle ID. A different bundle ID is a separate app with separate saves.
  • Deleting the app deletes its Documents folder, saves included.

On the Mac, saves are in ~/Library/Application Support/nxnative/<title ID>/save/.

The app is too big to install

Some games make apps of well over 10 GB. If yours will not install, pack it again with --romfs separate:

python3 scripts/build_ipa_from_nsp.py ~/Games/MarioWonder -k ~/keys/prod.keys --romfs separate

The game files then stay out of the IPA. At the end the script prints a push_romfs.sh command: run it once per game version, with the device connected, to copy the game files into the app's Documents folder as romfs.img. Rebuilds after that are faster too, because the game files are neither packed nor sent again. Run the command again after a new game version, or after deleting the app.

The packing script stops

  • Rosetta or Intel Python: the script needs a native arm64 Python 3.12 or newer. A Python from an Intel Homebrew runs under Rosetta, and the script stops when it finds one.
  • Missing iOS platform: an iPhone or iPad build needs Xcode's iOS platform, added under Xcode → Settings → Components.
  • Wrong Xcode: nxnative pins its shader compiler to the one in Xcode 27.1, and a different Metal compiler can stop the build. Install Xcode 27.1.
  • Language not available: a language passed with -l must be one the game has. The script prints the game's languages and stops otherwise.
  • Not enough space: the first build needs about twice the game's size plus 10 GB free.

A Mac app will not open

Mac apps from nxnative are not notarized. On a Mac the app was downloaded to, Gatekeeper blocks it until you allow it in System Settings › Privacy & Security. A Mac app also needs a Mac with Apple silicon. See Requirements.

The game runs at 30 fps

  • Some games reach 60 fps only with a specific update. Each game page says which one, where nxnative lists it; pack the game with that update in its folder.
  • Check Frame rate on the settings screen, and that env.txt does not set DM_FPS_TARGET=30.
  • With Hold frames when late on, a game drops to an even 30 fps for a while when frames come late. Turn it off to stay closer to 60 in heavy scenes. See Settings.