Diagnose and resolve every documented Hookshot v2.0.11 runtime crash, GPU driver hang, texture artifact, and builder extraction error. Search or filter the 10 verified fault sheets below by issue tag (#1161, #817, #57, #1176) or symptom, inspect the three ruled diagnostic panes (Symptom, Environment Flag, Resolution), and apply targeted RX_* environment overrides.
Occurs during heavy Hyrule Field or Temple transitions when the ASTC texture pool plus shadow cascades exceed physical VRAM or trigger a driver TDR timeout.
PANE 01 // OBSERVED SYMPTOM
Fatal VK_ERROR_DEVICE_LOST popup and crash to desktop during area load
PANE 02 // ENV VARIABLE OR FLAG
graphics_preset=Low/Medium or RX_SKIP_SHADERS=<hash>
PANE 03 // VERIFIED RESOLUTION
Lower Graphics Preset in Insert/F1 menu to Low (4 GB) or Medium (6 GB), reduce render scale to 1.0x, and update to v2.0.11 descriptor pool fix.
Issue #817Steam Deck / Linux RADV Inside the Deku Tree Freeze (#817)
Steam Deck LCD/OLED & Linux AMD RADV (Mesa < 24.3)
Entering Inside the Deku Tree or Web Room on Steam Deck (Mesa RADV) can hang the GPU command buffer due to meshlet subgroup culling on shader 2c56dc1006942f74.
PANE 01 // OBSERVED SYMPTOM
Screen freezes with audio looping upon entering Inside the Deku Tree
PANE 02 // ENV VARIABLE OR FLAG
RX_VK_MESH_NOCULL=2c56dc1006942f74
PANE 03 // VERIFIED RESOLUTION
Set Steam launch options to RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% (or RX_VK_MESH_NOCULL=1 to disable meshlet culling globally).
Certain AMD Windows Adrenalin and Linux drivers miscompile the compute ASTC-to-BC7 transcoder, producing colorful 4x4 macroblock artifacts on HUD icons and Kokiri foliage.
PANE 01 // OBSERVED SYMPTOM
Checkerboard or rainbow 4x4 blocks on UI icons, grass, and water surfaces
PANE 02 // ENV VARIABLE OR FLAG
RX_VK_ASTC_RGBA8=1
PANE 03 // VERIFIED RESOLUTION
Export RX_VK_ASTC_RGBA8=1 before launching Hookshot to force lossless software RGBA8 decompression instead of compute BC7 transcoding.
Asset builder aborts when given a base v0 dump without patch v131072, an N64/3DS ROM instead of Switch 2 Title ID 0400486024DEC000, or Windows paths with non-ASCII characters prior to v2.0.11.
PANE 01 // OBSERVED SYMPTOM
Builder reports Unsupported ExeFS Build ID or fails at 99% RomFS repack
PANE 02 // ENV VARIABLE OR FLAG
Require Title ID 0400486024DEC000 v131072 (e0f3ccfa)
PANE 03 // VERIFIED RESOLUTION
Update to Hookshot v2.0.11 (fixes UTF-8 Windows path bug #1176) and supply the merged Switch 2 v131072 dump matching SHA-1 prefix e0f3ccfa.
docs/DEVELOPMENT.mdIsolating Broken Custom or Driver-Specific Shaders (RX_SKIP_SHADERS)
All Vulkan 1.3 platforms
Skips draw calls for one or more 64-bit NVN2 shader hashes so players and contributors can pinpoint which SPIR-V pipeline triggers a driver crash or visual glitch.
PANE 01 // OBSERVED SYMPTOM
Specific particle effect or post-process pass crashes or blinds the viewport
PANE 02 // ENV VARIABLE OR FLAG
RX_SKIP_SHADERS=<hash1>,<hash2>
PANE 03 // VERIFIED RESOLUTION
Run with RX_LOG_LEVEL=debug to log the active shader hash before the crash, then pass RX_SKIP_SHADERS=<hash> to bypass that pipeline.
docs/DESIGN.md & docs/DEVELOPMENT.mdBypassing Lifted C Function Regressions via ARM64 Interpreter (RX_FORCE_INTERP)
Windows x64 & Linux x86_64
Routes individual guest function addresses (`0x7100xxxxxx`) or the entire binary through the software ARM64 interpreter instead of static C translations.
PANE 01 // OBSERVED SYMPTOM
Actor physics anomaly or softlock suspected in a lifted ARM64 function
PANE 02 // ENV VARIABLE OR FLAG
RX_FORCE_INTERP=0x7100123450 or RX_FORCE_INTERP=all
PANE 03 // VERIFIED RESOLUTION
Set RX_FORCE_INTERP to the suspect guest address to verify whether the bug stems from the nx2/ static C lifter.
Controls stdout/stderr verbosity from trace to error and logs entry/exit register states (`X0`–`X7`) for targeted guest functions when filing GitHub issues.
PANE 01 // OBSERVED SYMPTOM
Silent startup exit or unimplemented HLE service stub trap
PANE 02 // ENV VARIABLE OR FLAG
RX_LOG_LEVEL=debug / RX_ABORT_ON_UNIMPL=1
PANE 03 // VERIFIED RESOLUTION
Launch from terminal with RX_LOG_LEVEL=debug (and optionally RX_TRACE_FUNC=0x7100xxxxxx) to capture full diagnostic logs.
README.md Linux SetupLinux AppImage Fails to Launch (Missing chmod +x or libfuse2)
Linux x86_64 (Ubuntu, Debian, Fedora, Arch)
On Ubuntu 22.04/24.04 or minimal distros without libfuse2, double-clicking Hookshot-v2.0.11-Linux-x86_64.AppImage silently fails unless executable permissions or --appimage-extract are used.
PANE 01 // OBSERVED SYMPTOM
AppImage does not open or prints dlopen(): error loading libfuse.so.2
PANE 02 // ENV VARIABLE OR FLAG
chmod +x *.AppImage or --appimage-extract-and-run
PANE 03 // VERIFIED RESOLUTION
Run chmod +x Hookshot-v2.0.11-Linux-x86_64.AppImage and either install libfuse2t64 or pass --appimage-extract-and-run.
When a crash or softlock cannot be resolved by lowering VRAM presets, combine RX_LOG_LEVEL=debug with RX_SKIP_SHADERS=<hash> to test whether a specific NVN2 SPIR-V pipeline is responsible, or set RX_FORCE_INTERP=0x7100xxxxxx (or RX_FORCE_INTERP=all) to execute guest functions on the software ARM64 interpreter instead of static C.
FAILURE PATH INK SKETCHES // TOP 3 HEADLINE ISSUES
VK_ERROR_DEVICE_LOST Queue TimeoutHyrule Field / Temple Transition or NVIDIA 621 Driver Submit
ASTC texture pool + shadow cascades exceed physical VRAM or separate present queue triggers TDR timeout → Lower Insert/F1 preset to Low/Medium and run Hookshot v2.0.11.
Three hardware-specific issues account for the majority of community support reports in Hookshot. First, Issue #1161 (VK_ERROR_DEVICE_LOST) manifests in two distinct scenarios: on NVIDIA 621-series drivers immediately after startup shader preparation when a separate Vulkan present queue was active (mitigated in v2.0.9 and refined in v2.0.11 by keeping the separate present queue off while re-enabling RX_VK_WB_DIFF=1), or during heavy Hyrule Field / Temple transitions when the ASTC texture pool and shadow cascades exceed physical VRAM on 4 GB to 6 GB GPUs. Lowering the Graphics Preset in the Insert / F1 menu to Low (1.5 GB pool) or Medium (2.5 GB pool) prevents VRAM exhaustion.
Second, Issue #817 affects Steam Deck LCD/OLED and Linux AMD RADV systems running Mesa versions prior to 24.3: entering Inside the Deku Tree or the Web Room hangs the GPU command buffer while audio continues looping. The hang is triggered by subgroup meshlet culling inside NVN2 mesh shader 2c56dc1006942f74; setting Steam Launch Options to RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% bypasses culling for that specific shader with zero measurable FPS penalty. Third, Issues #57 and #1006 on AMD Radeon RX 6000 / RX 7000 GPUs cause rainbow 4x4 blocks on foliage and HUD icons due to driver miscompilation of the compute ASTC-to-BC7 transcoder; exporting RX_VK_ASTC_RGBA8=1 switches to lossless software RGBA8 decompression.
When HookshotBuilder fails during asset extraction or C compilation, verify three prerequisites: (1) your dump matches Switch 2 Title ID 0400486024DEC000 at update v131072 with ExeFS main NSO SHA-1 prefix e0f3ccfa (e0f3ccfa56256410941279ef0b2501356be2222c), not a base v0 dump or N64/3DS ROM; (2) you are running Hookshot v2.0.11, which fixes non-ASCII Windows user path failures (#1176), stale generated C translation conflicts (#1197), and missing Linux AppImage headers (#990); and (3) you have at least 30 GB of free disk space for the 26.2 GB unpacked RomFS plus 1.4 GB of generated C sources.
For advanced debugging, Hookshot exposes granular environment variables documented in docs/DEVELOPMENT.md: RX_LOG_LEVEL=debug and RX_ABORT_ON_UNIMPL=1 surface unimplemented Horizon OS HLE service calls; RX_SKIP_SHADERS=<hash1>,<hash2> disables specific 64-bit NVN2 shader pipelines to isolate visual corruption; RX_FORCE_INTERP=0x7100xxxxxx routes suspect guest functions through the software ARM64 interpreter; and RX_GPU_BACKEND=null pairs with RX_BOOT_DIRECT=1 for headless boot verification.
TECHNICAL FAQ // CRASHES, LAUNCH FLAGS & SAVE RECOVERY
Troubleshooting & Environment Flag FAQ
Where do I set RX_VK_MESH_NOCULL or RX_VK_ASTC_RGBA8 on Windows vs. Steam Deck?
On Steam Deck or Linux Steam, right-click Hookshot -> Properties -> Launch Options and enter: RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% (or combine multiple variables before %command%). On Windows PowerShell, run $env:RX_VK_ASTC_RGBA8=1; .\hookshot.exe from the build directory, or add the variable in Windows System Properties -> Environment Variables.
Why did upgrading from v2.0.7 to v2.0.9 fail with undeclared g_module_b or f_8 symbols (#1176 / #1197)?
Prior to v2.0.10, interrupted or cross-version updates could leave stale generated C files inside work/sa/gen/, causing clang/lld link errors. Updating to Hookshot v2.0.11 automatically discards stale partial generated code and cleans old translation shards before compiling.
How do I recover a save slot if Hookshot reports Corrupted Data after a crash?
First check the saves directory for autosave.sav and copy it over save_00.sav. If you edited a save file manually, run python -m nx2.oot_saves verify save_00.sav (or export-json followed by import-json) so Hookshot recomputes the required CRC32C checksum at header offset 0x0008.
PRIMARY SOURCES & VERIFICATION
Official NotRexed/Hookshot Diagnostic & Issue References
