Tears of the Kingdom Mac errors & fixes

ERROR: needs a Mac with Apple silicon

The game’s ARM64 code runs directly on the chip, so an Intel Mac cannot run it.

Next step

1. There is no Intel route for this project.

ERROR: needs macOS 26 or later (Metal 4); this is macOS <your version>

The graphics use Metal 4, which needs macOS 26. The version in the message is the one on your Mac.

Next step

1. Update macOS to 26 or later, then run the same command again.

Apple menu › About This Mac shows macOS 26 or later.

ERROR: the Xcode command line tools are missing: xcode-select --install

xcrun cannot find clang.

Next step

1. Install the command line tools, then run the build again.

xcode-select --install

xcrun --find clang prints a path.

Prepare the Mac build tools →

ERROR: clang++ finds no C++ standard library headers, so the developer tools or their SDK are incomplete.
(builds before 19 Oct stopped later: spirv_cross_error_handling.hpp:29:10: fatal error: 'string' file not found)

The selected developer tools have no macOS SDK with libc++ headers. It is not the game files or the repository.

Next step

1. Check which developer tools and SDK are selected using the first two commands.
2. If the command line tools are missing, use xcode-select --install. If they are installed but incomplete, repair or update the developer tools before retrying.
3. If full Xcode is already installed at /Applications/Xcode.app, select it with the last command and open Xcode once to finish setup.
4. Run the same build command again; it reuses the work folder and continues from the shader step.

xcode-select -p

xcrun --show-sdk-path

xcode-select --install

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

The build gets past “3/4 shaders: building SPIRV-Cross with clang”.

Issue #41 open; since commit 8b5b428 the check runs before the build starts

Issue #41 and the author’s reply ↗

Prepare the Mac build tools →

ERROR: Homebrew packages missing: brew install opus libvpx

The script looks for opus and libvpx under /opt/homebrew/opt/, which is where Homebrew installs on Apple silicon.

Next step

1. Install the packages it names. If Homebrew lives somewhere else (for example /usr/local from an Intel-era setup), the check still fails: use a native Apple silicon Homebrew in /opt/homebrew.

brew install opus libvpx python@3.14

ls /opt/homebrew/opt/opus/lib /opt/homebrew/opt/libvpx/lib lists files.

Set up Homebrew and build packages →

ERROR: Python 3.14 not found (the build reads zstd with the standard library): brew install python@3.14

The build makes its tool environment with python3.14 or python3.15 from /opt/homebrew/bin or /usr/local/bin. The python3 that comes with macOS is older (one player’s Mac had 3.9).

Next step

1. Install Python 3.14 with Homebrew and start the script with python3.14, not python3.

brew install python@3.14

python3.14 --version

python3.14 --version prints 3.14.x.

Community build notes (PR #55) ↗

Set up the required Python version →

ERROR: NSP files do not include system shared fonts. Supply --firmware <unpacked firmware NCA directory> or --shared-fonts <previously extracted font directory>; valid fonts in --work are also reused.

An XCI carries a system update with the six shared fonts; an NSP does not.

Next step

1. Add --firmware with a folder of unpacked firmware .nca files (or an installed firmware “registered” folder), or
2. add --shared-fonts with the folder that holds 0-standard.bfttf … 5-nintendo-extension.bfttf from an earlier build, or
3. build into a work folder that already has valid fonts from a previous build.

The log shows “2/4 data: extracting the system shared fonts” (with --firmware) and moves on.

Choose an NSP font source →

ERROR: the base game must be an uncompressed XCI or NSP; NSZ is supported for update packages
ERROR: --update must be a separate cumulative NSP or NSZ

The base game is read as an XCI or NSP container; NSZ/XCZ base games, DLC and combined packages are not supported. Updates are accepted only as a separate NSP or NSZ.

Next step

1. Use the uncompressed base 1.0.0 as XCI or NSP.
2. Give the update separately with --update (NSP or NSZ).

The build reaches “1/4 code: extracting the ExeFS from the game file”.

Choose the base and update inputs →

ERROR: unsupported update module hashes; expected 1.1.2, 1.2.1 or 1.4.3 (the file name is not used to choose a version)

The update’s code modules did not match 1.1.2, 1.2.1 or 1.4.3. Renaming the file does not change this.

Next step

1. Use the separate cumulative update for one of those three versions.

The log shows “update identified by verified ExeFS hashes: 1.x.x”.

Choose a supported game version →

ERROR: needs about 25 GB free for the work folder (the app itself is an APFS clone of it when on the same volume)
ERROR: needs about 40 GB free for a fresh base + update build (19 GB extra with base data cached)

The work folder holds the extracted 17 GB game data and the build files.

Next step

1. Free space on the volume that holds the work folder, or point --work at a bigger APFS volume.
2. Keep the app on the same volume (-o) so it is a clone, not a 17 GB copy.

The first log line shows the free space on the work folder’s volume.

Calculate space for your build →

ERROR: ExeFS main.npdm: SHA-256 890c6174a3160551... is not the expected f5a5eecc49bbc31d... (is this Tears of the Kingdom 1.0.0, and the dump complete?)

Your dump’s main.npdm differs from the author’s reference dump. Since 19 Oct a Nintendo-signed main.npdm of the same version is accepted; a file that is neither the pinned one nor signed is still rejected.

Next step

1. Switch to the project version used by the build guide and run the same command again.
2. If it still stops here, compare the other ExeFS hashes in the log and see issue #65.

git fetch origin
git checkout b75be8cfa704df3701e86130c8ced268e79d6b11

The log shows “main.npdm is a Nintendo-signed 1.0.0 file from another dump; using it”.

Fixed for signed files (PR #47); unsigned case open (#65)

Issue #45 ↗ · PR #47 ↗ · Issue #65 ↗

Get the matching project source →

ERROR: shared font <name>: not the expected bytes and not a valid BFTTF font (SHA-256 …)

Fonts from another firmware version are accepted when they are valid BFTTF files. This error means the file itself is not a valid font.

Next step

1. Unpack the firmware again, or use the fonts folder of an earlier successful build with --shared-fonts.

The log says the font “comes from another firmware version; its bytes are bound instead”, or nothing about fonts.

Other-firmware fonts accepted since PR #47

Issue #45 ↗

Get the matching project source →

ERROR: extract_update_romfs.py failed (exit 1); full output: …/TOTK_build/logs/update-romfs.log
ValueError: BKTR verification failed

Two causes were fixed on 19 Oct: prod.keys written by Lockpick_RCM with a trailing NUL byte (PR #24), and hactool’s two signature lines it cannot verify, “Fixed-Key Signature (FAIL)” and “NPDM Signature (FAIL)” (PR #46).

Next step

1. Switch to the project version used by the build guide and run the same command again. Your prod.keys file itself is not changed by the fix.

git fetch origin
git checkout b75be8cfa704df3701e86130c8ced268e79d6b11

The log shows “2/4 update: merging base + 1.x.x and verifying all IVFC levels” followed by “3/4 shaders”.

Fixed in main (PR #24, PR #46)

Issue #23 ↗ · Issue #44 ↗

Get the matching project source →

ERROR: …/prebuilt/macos-arm64/totk_xlate: not the shader translator this repository ships (its SHA-256 differs from totk_xlate.sha256); check it out again …

The prebuilt translator in your copy of the repository is damaged or changed.

Next step

1. Download or clone the repository again (the file is part of it).

The build reaches “3/4 shaders: discovering and translating startup shaders”.

Get a clean project source →

ERROR: the app does not start: …

At the end the script runs the app once with --check so macOS can do its first-launch scan; that run failed.

Next step

1. Read the text after “does not start:”.
2. Look at the logs folder inside the work folder for the step that wrote last.

The log shows “checked in … s”.

Find the stage that stopped →

Stutter when a scene appears for the first time; or “warming shaders” for minutes on the first start after moving the app

New shaders compile the first time they are met; this is expected. Without Xcode’s Metal toolchain, the startup shaders are compiled into macOS’s Metal cache for the app’s location, and that cache does not follow the app when you move it (also not to /Applications).

Next step

1. Build with -o pointing at the final location, for example -o "/Applications/Tears of the Kingdom.app", instead of moving the app afterwards.
2. Or install Xcode’s Metal toolchain so the startup shaders are compiled into the app (first command), then rebuild.
3. Do not run another game while building: the build skips the warm-up when another program has Metal’s cache open.

xcodebuild -downloadComponent MetalToolchain

Later visits to the same places stutter less; the second start after a build does not warm for minutes.

Review shaders and app location →

Dialogue missing or background music falls silent after a short fragment

Streamed audio could not be opened because of a path bug fixed on 18 Oct. Other causes are the output device, and audio underruns on 1.4.3 that the author still investigates.

Next step

1. Rebuild with the source version from the build guide (saves and shader cache stay).
2. Check the macOS output device and play a system sound.
3. Look in the game log for CoreAudio or decode errors.
4. For a file-open log, quit the game and start it with TOTK_FS_LOG=1 (last command).

open ~/Library/Logs/MacNativeGames/totk.log

open --env TOTK_FS_LOG=1 "/path/to/Tears of the Kingdom.app"

The opening scene plays dialogue and music through the device you chose.

Path bug fixed; 1.4.3 underruns under investigation; PR #64 open

PR #64 ↗

Rebuild from the matching source →

[totk] FAIL: hardware Opus decoder table full

Decoder slots leaked when the game set up the same decoder again; the table filled after about ten minutes.

Next step

1. Rebuild with the source version from the build guide.

Long sessions no longer end with that line.

Fixed in main (PR #18, PR #40); issue #9 closed

Issue #9 ↗

Rebuild from the matching source →

[totk] signal=0x000000000000000a … main offset=0x000000000001561c

A pointer the game keeps for an optional target refers to freed memory after long play.

Next step

1. Rebuild with the source version from the build guide, which includes e8b5259.
2. If it happens again, add the log lines to issue #57 (no game files, keys or saves).

Instead of a crash the log shows “[totk] ignored a stale optional target reference (#57)”.

Mitigation in e8b5259; issue still open for long-session retests

Issue #57 and the author’s reply ↗

Rebuild from the matching source →

[totk] FAIL: reserve the 64 GiB alias region at 0x70_0000_0000

macOS 27 changed the address-space layout the game memory used.

Next step

1. Rebuild with the source version from the build guide.

The game reaches the title screen.

Fixed in main (PR #11); issue #8 closed

Issue #8 ↗

Rebuild from the matching source →

~/Library/Application Support/MacNativeGames/TOTK/controls.txt, line 3: unknown Switch button (a b x y l r zl zr plus minus lstick rstick up down left right none)

The launcher checks your controller layout file at every start and stops at the first bad line.

Next step

1. Close the game, keep a copy of controls.txt, then paste its text into the file checker to repair the reported line.
2. To restore defaults instead, move controls.txt out of the TOTK folder and restart. Keep that file if you want the custom layout later.

The game starts without the alert.

Check and repair your controls.txt →

The right face button should be A, as the game prompts show

Since 19 Oct face buttons map by position on every controller: right = A, bottom = B, top = X, left = Y. Older builds mapped them by label.

Next step

1. Rebuild to get the by-position mapping, or start the game with TOTK_FACE_BUTTONS=label to map by label.
2. For any other change, use a controls.txt.

open --env TOTK_FACE_BUTTONS=label "/path/to/Tears of the Kingdom.app"

The button the game shows as A is the one you press.

Changed in main (issue #10 closed)

Issue #10 ↗

Choose button positions and press behavior →

Grass shows no cut/destruction animation when cutting with a weapon

Metal lacks some sampler border colours the game uses.

Next step

1. Rebuild with the source version from the build guide (commits b6231e6 and 874a32d).

Cutting grass shows the animation.

Fix in main; issue #49 still open on 20 Oct

Issue #49 ↗

Rebuild from the matching source →

The game closes in busy areas after several minutes (iPhone 14)

The game uses close to 4 GB, near what the phone allows; iOS closes it when memory runs out.

Next step

1. No fix yet; the author names lowering iOS memory use as the next piece of work.

Known issue (README, iPhone and iPad)

Read the iPhone and iPad limits →