Hookshot Builder Troubleshooting: Build, Launch & Vulkan Errors

Builder does not open

• Windows: use the official HookshotBuilder.exe and an internet connection for its initial download. Investigate security warnings and verify the source; do not disable system protection globally.
• Linux: confirm x86-64, glibc 2.35+, AVX2 and executable permission on the AppImage. Launch from a terminal if needed to read the error.
• For an older Windows ZIP only, extract everything and keep the tools folder with the EXE. Current bootstrap installs manage their own tools.

The build fails or stops

The README describes a Repair action for tools removed by antivirus. Verify provenance and investigate the detection before restoring or repairing anything; never apply blanket exclusions to unknown downloads.

1. 1

   Record the failing stage and complete error text before closing Builder.

2. 2

   Check about 60 GB of available build space, a writable output location and an intact official package.

3. 3

   Confirm your game’s supported identifiers and a complete .nup or matching romfs/exefs pair.

4. 4

   Check the latest release and search existing issues with the error text. Report the Builder output if the failure persists.

Unsupported game version

Match the Program ID, game update and build on the supported-version page. The current message may say Hookshot supports build e0f3ccfa. Renaming the file or using a different Builder release does not change your game’s build.

Black screen, crash or missing geometry

Install a current driver for your actual GPU and confirm the game uses the intended device. Vulkan 1.3 and mesh shaders are mandatory. Hardware without mesh shaders has no supported fallback.

Read hookshot_log.txt in the game folder; the four previous runs are hookshot_log.1.txt through hookshot_log.4.txt. When launched from a terminal the game prints there instead. Device-lost errors have known AMD reports, but the message alone does not establish the cause on your PC.

The checked release fixes dark faces, shader preparation and an AMD terrain grid. Floating trees and Gerudo Valley terrain holes remain in its known issues. Update and read the current notes before assuming an older workaround is still necessary.

First-visit stutter and shader preparation

The first start prepares shaders and can take several minutes; the checked release prepares them again after updating. New areas may still stutter on first visit, with later visits smoother according to the README.

Try a lower Graphics quality preset for limited VRAM and change one option at a time. Frame generation can add artifacts and delay; it is not a guaranteed fix for low native performance. No universal 60 FPS claim is supported.

Check Vulkan on Linux

With the vulkaninfo utility installed, the following query should list VK_EXT_mesh_shader. Also confirm Vulkan 1.3 support for the device in its full output. If the extension is absent, check the driver and GPU capabilities.

vulkaninfo | grep mesh

Make a useful project report

• Try the latest official release and search for the same problem first.
• Provide release version, OS, GPU/driver, CPU, RAM, location in game and reproducible steps.
• Attach relevant logs and, if appropriate, a screenshot or video. Do not attach game data, keys or generated builds.
• The project contribution guide asks for reports in English. This website is not the official support team.