Troubleshooting

Start troubleshooting with Norn’s read-only readiness probe:

norn doctor --repo-path .

Use JSON when attaching sanitized diagnostics to automation or a bug report:

norn doctor --repo-path . --format json

Command not found

Restart your shell after Homebrew installation and confirm the active binary:

which norn
norn --version
norn-tui --version

If necessary, repair and update the tap:

brew tap --repair
brew update
brew upgrade delaudio/tap/norn

Repository is not detected

Run Norn from inside a Git checkout with a GitHub or Bitbucket remote. Check:

git rev-parse --show-toplevel
git remote -v
norn doctor --repo-path .

Use norn-tui --workspace when you want to select from repositories already configured in the app instead of resolving the current checkout.

Invalid repository config

Validate without starting a review:

norn config validate --repo-path .

Do not keep .norn.yaml and .norn/ together. Keep .norn.local.yaml untracked and ignored. Remove credential-like keys from all repository config.

For legacy .lachesi* files, preview migration first:

norn config migrate --repo-path . --dry-run --format json

Provider credentials are missing

Inspect sanitized state and configure the missing provider through the terminal:

norn auth status
norn auth login github
norn auth login bitbucket --username <username>

You can also use environment-variable references in ~/.config/norn/config.toml. Confirm referenced variables are available to the process that starts Norn. Doctor reports availability without revealing values.

Agent skill is missing or stale

Inspect both supported destinations and reinstall the version bundled with the active Norn release:

norn skills status --agent all
norn skills install --agent all

If status reports unmanaged content, inspect it before deciding whether to use --force. Norn never overwrites or removes an unmanaged skill implicitly.

brew upgrade norn updates only the packaged source. A status of upgrade_available means the personal managed copy still needs norn skills install --agent all. A status of unmanaged commonly identifies an older manual directory or symlink; use --force only after confirming that Norn may replace it.

Claude or Codex review fails

Confirm the selected CLI is installed, authenticated, and runnable in the same shell:

claude --version
codex --version
norn doctor --machine-only

If JSON output reports review.diffConsentRequired, the diff was not sent. Authorize one exact run with --allow-provider-diff, or persist your local choice with:

norn setup --allow-provider-diff --yes

If Norn reports review.sandboxRestricted, approve the exact norn review command outside the Codex or Claude Code sandbox. Diff-sharing consent does not grant this host permission, and Norn never changes agent permission settings.

review.providerTimeout means the local provider CLI did not finish within the bounded wait. Confirm that no hidden login or permission prompt is waiting, then retry once with the required host permission.

Branch review misses local changes

Branch scope includes committed changes only. Review uncommitted changes separately:

norn review --repo-path . --scope branch
norn review --repo-path . --scope working-tree

Report a security issue

Do not open a public issue containing credentials, private source, or local machine paths. Use GitHub Security Advisories for vulnerabilities and rotate any credential that may have been exposed.