Troubleshooting nxnative
Most problems come from missing tools, low disk space or a game the project does not support yet. Work through these checks in order.
| What you see | Go to |
|---|---|
| The first build is very slow | Read the fix |
| The build runs out of disk space | Read the fix |
| Your game is not on the supported list | Read the fix |
| The wrong version was packed | Read the fix |
| The build stops before it starts extracting | Read the fix |
| The build stops at the Metal compiler | Read the fix |
| The game has no language you chose | Read the fix |
| Motion controls misbehave | Read the fix |
| The IPA is too big to install | Read the fix |
| Where to look and where to report | Read the fix |
The first build is very slow
This is expected. The project says the first build takes 30 to 60 minutes, and later builds are much faster. The extracted game files are kept by default, so the next build skips extraction.
The build runs out of disk space
Free at least twice the game's size plus 10 GB. The build folder sits in your game folder, so check the drive that holds it. Use --work-dir to put it on another drive, or --no-keep-extracted to delete the extracted game files after each build.
Your game is not on the supported list
For an unsupported game the script writes a survey to <title ID>_survey/survey.md and still tries to pack an IPA by guessing settings. Such an IPA may not start. Compare your game with the tested games list first.
The wrong version was packed
The script reads the title ID from the package (or the [title ID] in the file name) and an update's version from its [vN] tag, and it packs the newest version in the folder. Use -p v0, for example, to pack another version. The folder still needs both NSPs.
The build stops before it starts extracting
The script checks your Mac first. It stops if a Python module or tool is missing, if the iOS SDK is not installed (for an iPhone build, add Xcode's iOS platform under Settings, then Components), if the Metal compiler is missing, or if the shader translator finds no .NET 10 runtime for its architecture. A Python that runs under Rosetta, such as one from an Intel Homebrew, stops it too. Use an arm64 Python.
The build stops at the Metal compiler
An NVN game's shaders are built with Xcode 27.1's Metal compiler, and the build stops when the compiler is another version. Install Xcode 27.1 from Apple's download page next to your newer Xcode, rename it Xcode-27.1.app and select it:
sudo xcode-select -s /Applications/Xcode-27.1.appThe script has an --allow-other-metal switch, but the project has seen corruption with an untested compiler (issue 242), so it is not recommended.
The game has no language you chose
The script stops with a message that lists the game's languages. Pick one of those with -l. English is the default, and if the game has no English the script uses the game's first language.
Motion controls misbehave
Build again with --no-motion. In the app, DM_PHONE_MOTION=0 in Documents/env.txt stops the phone's gyro and DM_MOTION=0 stops all motion. DM_MOTION=1 turns it back on.
The IPA is too big to install
Rebuild with --romfs separate and run the copy command the script prints. See the sideloading guide.
Where to look and where to report
Logs are in <title ID>_build/ inside your game folder. For bugs in nxnative itself, use the official issue tracker, not this site.
A problem with one game
Each game has its own notes with what was found and what is still open. Search for your title on the games page, then read the sections called "Found on this game" and "Open".