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 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

Configure credentials in the desktop app or provide environment-variable references in ~/.config/norn/config.toml. Confirm the variables are available to the process that starts Norn. Doctor reports availability without revealing values.

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 Norn is running inside another sandbox or agent, the provider CLI must be allowed to access its own configuration directory. A read-only repository sandbox does not necessarily imply a read-only provider home directory.

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.