NX2navi troubleshooting
nx2 navi crashes and shader stutter are common searches because the project is days old. Start with the log, then the GPU, then the dump.
Order to check
- Read the end of logs\nx2navi.log for FATAL, the exit code, and the GPU name.
- If the game is open, the F10 overlay shows GPU busy, frame time, and memory. The controls notes describe that overlay.
- Confirm the dump line says Ocarina of Time 1.1.1, build e0f3ccfa.
- Confirm Vulkan 1.3 and VK_EXT_mesh_shader. A missing extension is not a missing runtime pack.
- Change one nx2navi.ini key at a time, after the checks above.
Symptom table
| Symptom | Trigger | Cause | What to try | Reported versions | Issues | Source status |
|---|---|---|---|---|---|---|
| Black screen; HUD or title may remain visible | Launch, cutscene, driver or unsupported-platform path | Several reported causes: Vulkan driver failures, missing mesh shaders, integrated-GPU memory limits or shader translation. | Read the log and GPU name; compare the dedicated black-screen branches. Update drivers and back up caches before rebuilding them. | 0.5.0–0.6.1 | #46, #141, #155, #208, #265, #267, #300, #317, #329, #345 | 10sources Independent user report #46 · 2026-11-10 Independent user report #141 · 2026-11-10 Independent user report #155 · 2026-11-10 Independent user report #208 · 2026-11-10 Independent user report #265 · 2026-11-10 Independent user report #267 · 2026-11-10 Independent user report #300 · 2026-11-10 Independent user report #317 · 2026-11-10 Independent user report #329 · 2026-11-10 Independent user report #345 · 2026-11-10 Project documentation (same publisher) · 2026-11-10 |
| Window closes at launch | Driver, Vulkan, cache or game-inspection failures | The exit code alone does not identify the cause. | Read the final FATAL line; check the required Vulkan extensions and the launcher inspection result; attach logs to a matching issue. | 0.5.0–0.6.1 | #141, #208, #300, #319, #345, #347, #395 | 7sources Independent user report #141 · 2026-11-10 Independent user report #208 · 2026-11-10 Independent user report #300 · 2026-11-10 Independent user report #319 · 2026-11-10 Independent user report #345 · 2026-11-10 Independent user report #347 · 2026-11-10 Independent user report #395 · 2026-11-10 Project documentation (same publisher) · 2026-11-10 |
| Short pauses on first visits or after updates | A new area, effect, install or graphics driver | The driver still builds some pipelines even though game shaders are prepared. | Allow normal preparation to finish; retain the cache unless corruption is indicated; compare issue #32. | 0.4.0–0.6.1 | #32, #323 | 2sources Project documentation (same publisher) · 2026-11-10 Project documentation (same publisher) · 2026-11-10 Independent user report #32 · 2026-11-10 |
| 16 GB system-memory exhaustion | Memory-intensive areas, including Hyrule Field | Project notes confirm this risk; individual reports vary by settings and hardware. | Close memory-heavy applications and try lower resolution or frame-generation settings; record logs if the crash continues. | 0.6.0–0.6.1 | #240, #259, #336 | 2sources Independent user report #240 · 2026-11-10 Independent user report #259 · 2026-11-10 Independent user report #336 · 2026-11-10 Project documentation (same publisher) · 2026-11-10 |
| Video-memory pressure or allocation failure | Higher resolution or frame generation on memory-limited GPUs | Reports describe allocation failures; no project-wide VRAM minimum is published. | Try lower resolution and disable frame generation; keep each hardware report separate rather than infer a universal VRAM threshold. | 0.6.0–0.6.1 | #240, #259, #336 | 2sources Independent user report #240 · 2026-11-10 Independent user report #259 · 2026-11-10 Independent user report #336 · 2026-11-10 Project documentation (same publisher) · 2026-11-10 |
| AMD integrated GPU fails at title or area load | Integrated Radeon graphics, including 5600G and Legion Go S reports | Project notes describe a host-memory-heap limit. | Compare the issue and required extensions; select an existing discrete GPU where available. No general integrated-GPU fix is established. | 0.5.0–0.6.1 | #155, #317 | 2sources Independent user report #155 · 2026-11-10 Independent user report #317 · 2026-11-10 Project documentation (same publisher) · 2026-11-10 |
| Mesh draws skipped; missing geometry or crash | GPU or driver does not expose VK_EXT_mesh_shader | The project requires this Vulkan extension and publishes no fallback. | Check the extension list and a current driver. A runtime download cannot supply an unsupported GPU feature. | 0.5.0–0.6.1 | #222, #329, #361 | 3sources Independent user report #222 · 2026-11-10 Independent user report #329 · 2026-11-10 Independent user report #361 · 2026-11-10 Project documentation (same publisher) · 2026-11-10 |
| Device lost or upload-submit failure | Area changes, driver problems or memory pressure | v0.6.1 fixes one freed-texture path; other reports remain hardware-specific. | Update to v0.6.1, check the driver and reduce memory pressure; compare the exact log and version with the linked report. | 0.6.0–0.6.1 | #335, #344, #361 | 3sources Independent user report #335 · 2026-11-10 Independent user report #344 · 2026-11-10 Independent user report #361 · 2026-11-10 Project documentation (same publisher) · 2026-11-10 |
| Random red flashes with HUD still visible | RX 9070 XT reports on 0.6.1 | Cause is not established by the cited reports. | Compare the affected version and scene with the issue; a rollback is a reported workaround rather than a general fix. | 0.6.1 | #331, #280, #374 | 3sources Independent user report #331 · 2026-11-10 Independent user report #280 · 2026-11-10 Independent user report #374 · 2026-11-10 |
| Crash when opening settings | Some AMD Radeon GPUs on 0.6.1 | Listed as a known issue in the release notes. | Back up nx2navi.ini and change documented settings there while following release updates. | 0.6.1 | 1source Project documentation (same publisher) · 2026-11-10 | |
| Inspect Your Game stops with exit code 1 | Unusable or incompatible input file; path or inspection error | The launcher inspection result is the evidence; a file-size guess does not establish integrity. | Check the inspection log for the required game version and build. Keep the original files and include the report in an issue. | 0.6.1 | #347, #395 | 2sources Independent user report #347 · 2026-11-10 Independent user report #395 · 2026-11-10 Project documentation (same publisher) · 2026-11-10 |
| SmartScreen warning or antivirus detection | Unsigned Setup; separate antivirus reports | SmartScreen signing status and malware detection are different signals; no malware verdict is established here. | Use GitHub Releases and compare the SHA-256. A matching digest confirms identity only; review a security warning before deciding whether to run the file. | 0.4.0–0.6.1 | #8, #135, #194, #227, #293 | 5sources Independent user report #8 · 2026-11-10 Independent user report #135 · 2026-11-10 Independent user report #194 · 2026-11-10 Independent user report #227 · 2026-11-10 Independent user report #293 · 2026-11-10 Project documentation (same publisher) · 2026-11-10 Project documentation (same publisher) · 2026-11-10 |
| Proton tools or Linux shader/build failure | Steam Deck, Proton, Wine or native Linux source builds | The launcher and Setup are Windows-only; public Linux reports describe different failure paths. | Compare the exact issue and source-build documentation. The Hookshot Deck video describes a different project and establishes no NX2navi compatibility result. | 0.5.0–0.6.1 | #36, #186, #258, #265, #267, #298 | 6sources Independent user report #36 · 2026-11-10 Independent user report #186 · 2026-11-10 Independent user report #258 · 2026-11-10 Independent user report #265 · 2026-11-10 Independent user report #267 · 2026-11-10 Independent user report #298 · 2026-11-10 Project documentation (same publisher) · 2026-11-10 Project documentation (same publisher) · 2026-11-10 |
Memory and shader stutter
16 GB machines can run out of memory in Hyrule Field. Issues 240, 259, and 336 describe that pressure, including VRAM at higher resolutions. Shader compilation stutter on a first visit is listed separately: it is the driver building pipelines, and it is called out from 0.4.0 onward. AMD integrated GPUs failing the title screen are issues 155 and 317. Some discrete AMD cards crash when the F1 settings menu opens; the 0.6.1 notes are the only place I have that, so I would edit the ini instead of opening the menu until a second source appears.
Vulkan
If the log says mesh draws were skipped, the card or driver has no VK_EXT_mesh_shader. Issues 222, 329, and 361 cover that path. There is no fallback mode to enable.
Black screen branches · Requirements · SmartScreen and Defender
Questions
Where is the log?
The release notes point at logs\nx2navi.log. Read the last FATAL line, the exit code, and the GPU name before changing settings.
Is first-area stutter a bug?
The project treats the first visit to an effect as shader preparation. Issue 32 matches that. The same area should be smoother the next time.
My antivirus blocked Setup. Is that the crash page?
That is the safety page. The Setup is unsigned, which explains SmartScreen warnings; antivirus detections are separate user reports. A matching digest establishes file identity, not safety.
Sources
- Project readme · checked 2026-11-10
- Release v0.6.1 · checked 2026-11-10
- Issue list · checked 2026-11-10