Troubleshooting

Troubleshooting

Exit 20

A user-owned external action is pending—commonly WSL restart, Windows Terminal reload, Android permission, companion app, authentication, or reviewed settings. Follow the exact message and rerun the same command. --yes never bypasses a manual host checkpoint.

If phase 90-verify creates wsl-interop-restart, Windows PE execution failed even if powershell.exe and clip.exe paths exist. From Windows PowerShell run wsl --shutdown; warning: this stops every running WSL distribution. Reopen j3w1zsh - arch wsl, then run j3w1zsh install --only 90-verify. j3w1zsh never performs the shutdown itself, the continuation does not repeat phase 20 or a Pacman refresh, and the checkpoint clears only after a harmless PowerShell execution probe succeeds.

For the exact Corepack/Pacman pnpm collision, confirm the reported resolved targets are owned by Pacman package corepack. j3w1zsh preserves both shim paths. Only after that ownership review should the owner run the displayed sudo corepack disable pnpm --install-directory /usr/bin, verify /usr/bin/pnpm and /usr/bin/pnpx are absent, and rerun phase 20.

Exit 21

Git or migration found protected authored, staged, untracked, deleted, renamed, ahead, divergent, or unique-commit state. Inspect the listed paths and recovery root. Do not reset, clean, rebase, or force-push merely to continue.

Package collision exit 21 means an existing pnpm or pnpx path did not match the complete Corepack-owned shim contract. Do not delete or overwrite it. Establish exact type, target, and package ownership before deciding how to proceed.

If git -C ~/j3w1zsh status --short --branch reports [gone], do not reset, reclone, or roll back an otherwise successful migration. Follow the exact-commit --repair-tracking procedure in Migrating from the Former Project. It refuses dirty, unique, divergent, noncanonical, or mismatched state and does not change HEAD or checkout files.

Doctor reports git-upstream

j3w1zsh doctor resolves the configured upstream from local Git data only; it does not contact the network. A failed git-upstream check means the upstream is absent or its local tracking ref cannot resolve. Inspect git status --short --branch, branch configuration, and local refs before using update.

Doctor reports wsl-interop

The WSL runtime could not execute a harmless non-interactive Windows PowerShell command. File existence is not sufficient health evidence. Do not alter the Neovim clipboard mappings or mutate the clipboard as a diagnostic; follow the bounded full-WSL restart checkpoint above.

Unsupported platform

Run j3w1zsh platform --json. WSL must be version 2 and official Arch. Native Linux must be official Arch. Termux must be the native main environment and not root.

Missing package in --no-packages

The flag intentionally acquires nothing. Install the reported prerequisite through the platform owner or rerun without the flag after reviewing the plan.

Windows font or phase 50

An exact pinned current-user font is idempotent even while Windows Terminal is using it; j3w1zsh hashes and reuses the regular non-reparse file without replacement. A future changed pin installs beside the old file under a SHA-256-addressed filename and updates only the owned HKCU font registration. Do not delete the old file merely to continue.

If phase 50-theme reports a mismatched content-addressed font or an unsafe/reparse-point destination, leave the file in place and inspect its type, digest, path ownership, and registry reference. The adapter fails before its phase marker and before phases 60-90. The windows-terminal-restart checkpoint appears only after verified font and fragment reconciliation succeeds.

Candidate workspace cannot apply

Review all fields, ensure the current platform has an explicit target, set review_state to approved, commit the profile and referenced sources cleanly, then apply and confirm the displayed SHA-256.

Wiki pin unavailable

Normal synchronization follows only wiki-lock.json. A pending or unreachable commit is a publication/lock error; do not silently follow latest. Owners publish the Wiki first, verify reachability, then update the code lock.