Repository navigation
Every failure message should tell the user what to do next (dependencies first) #141
Description
Every failure a user can hit should tell them what to type or click next. Today two reports cost a diagnosis round-trip each because the message stopped at the symptom:
- a broken Homebrew (
/opt/homebrew is not writable) makes the five dependency rows fail in under a second, with the brew output only in the log the user never opened — see the diagnostics in the dependency-install report; - a
romfs.imgbuild on 0.5.0 died at the shader split withzstd ... returned non-zero exit status 1without saying "this image contains files zstd cannot open by path — update the repository" (issue Shader split fails on RomFS.img builds: please pull nxnative 35e1b6e into dm/ #118).
What to do
Walk every user-facing failure path and make the message self-solving: what failed, why in one sentence, and the exact command/button to fix it. Cover at least:
- Dependencies: brew missing / brew present but not writable / a package install fails (show the brew error line inline, under the row, not only in the log); Python too old vs missing vs venv creation failed; .NET missing.
- Keys: prod.keys missing or unreadable; a container the check cannot read (state that the build proceeds).
- Game files: damaged NSP (re-dump or
--allow-damaged); a folder with several games; a stale.nx2apple-library; game data on an unmounted drive. - Build steps: Rosetta Python, missing iOS SDK, missing glslangValidator/Metal toolchain, disk space, Xcode signing (team taken → team variant retry; no certificate → sign in to Xcode), devicectl transfer failed.
- Runtime: the launcher's "no game data" state (already improved), a re-signed build's stale bookmark (already improved).
Each row gets the message text in en + zh, a test that the string contains the actionable part (the command or the button name), and — where the app can do it itself — a button next to the message instead of a sentence ("Fix ownership…", "Open Xcode accounts", "Update repository").
The pattern to copy is the keys row: it names the missing key and the firmware generation, and never shows key values.
Closing note for whoever takes it: this replaces the bundled-tools direction for now (PR #121 was declined on its macOS floor), so the messages are the only path a Homebrew-less user has.
Activity
v0lumehi commentedon Oct 28, 2026
Status: the dependency half is in. #150 makes a failed install name its reason and the fix inline. The
romfs.img/zstdcase from #118 is also fixed. Still to walk: keys, damaged NSPs and the remaining build steps. Leaving this open as the tracker. Reports of messages that still stop at the symptom are welcome here.v0lumehi commentedon Oct 29, 2026
Status, checked against the launcher's failure rows on main:
Done
romfs.imgand zstd (Shader split fails on RomFS.img builds: please pull nxnative 35e1b6e into dm/ #118)Still to do
prod.keysmissing or unreadable as its own failure row (the onboarding checks keys, the build failure does not name the fix yet).nx2apple-library, game data on a drive that is not mounted, and "no NSP with a readable title ID" after the key check passed (NX2Apple 0.5.0 — No NSP with a readable title ID #177)The open items are in progress as one PR, following the failure-row pattern from #205.
v0lumehi commentedon Oct 29, 2026
Done with #215, so closing the tracker. Every item from the checklist above has its row now: keys, several games in a folder, no readable title ID (#177), a drive that is not mounted, a full disk, Xcode signing (team taken, no account or certificate) and a failed transfer to the device. The stale
.nx2apple-libraryis left out on purpose: the launcher only reads it to find the log folder, so a stale one causes no failure to explain. Two upstream follow-ups are noted in #215 (a distinct script line for an unreadable keys file, and a reason from the device steps). Messages that still stop at the symptom are welcome as new issues.Failure rows for keys, game files and the build's own steps