Troubleshooting

Start with the redacted diagnostic surface:

odinn doctor
odinn status

odinn doctor reports release identity and a safe diagnostic summary. odinn status reports current configuration and runtime health.

Onboarding or provider verification fails

Run:

odinn onboard

Choose Repair connection. Ódinn distinguishes common categories:

• rejected credentials;
• exhausted usage or rate limits;
• unavailable model;
• provider timeout;
• offline local server;
• port conflict.

Confirm that the expected provider environment variable is available to the current terminal. For Ollama or another local server, verify that the service is running and that the configured model name exists.

Then retry:

odinn onboard --verify --non-interactive

Console will not open

odinn start --no-open

Read the terminal result. If another healthy gateway already owns the port, Ódinn should use the existing console rather than bind a duplicate.

Never solve a port problem by binding the single-user gateway publicly.

Browser action is blocked

An interrupted or uncertain mutation blocks later browser changes. Open the console, inspect the recovery item, verify the remote account directly, and mark the outcome only after you know what occurred.

Do not delete browser recovery files by hand.

Audit verification fails

odinn audit verify

Stop mutating the affected state. Create a secure backup, preserve the exact error, and avoid hand-editing the journal. A verification failure is evidence to investigate, not a formatting nuisance.

Upgrade behaves incorrectly

Use installer status and rollback from the extracted release tree:

node scripts/install.ts status --prefix "$HOME/.local/share/odinn"
node scripts/install.ts rollback --prefix "$HOME/.local/share/odinn"

Application rollback does not automatically revert runtime state. See State, backup, and restore.

Still blocked

Collect safe diagnostics and open an ordinary bug report. Use private vulnerability reporting for security issues.