| Symptom | Check / action |
|---|---|
Missing node/npm | Reopen the terminal, load nvm, or fix PATH. |
| Node below 20 | Upgrade before installing or building. |
npm start fails on Windows | Use WSL2; native help: node bin/cockpit.js --help. |
| Missing backend build | npm run build or npm run build:all. |
| SPA not built | npm --prefix web ci, then npm run build:web, or use --headless for API-only. |
| Missing web dependencies | Root installation is not enough; run npm --prefix web ci. |
| Lockfile error | Check manifest and lockfile revisions; do not start by deleting lockfiles. |
EADDRINUSE | Use --port 4100 or stop the existing instance. |
Missing agent / ENOENT | command -v <runner> in the server environment; restart after installation. |
| Installed agent fails | Verify authentication, model, and access directly in the CLI. |
| No TTY/resize | Check ptyBackend, python3, and POSIX imports; pipe is limited. |
Invalid HEAD | Create an initial commit and check git rev-parse HEAD. |
| Permission denied | Use a writable folder and verify ownership; do not run as root. |
dubious ownership | Check repository ownership and adjust only the verified target. |
.env/worktree rejected | Check configuration, containment, and allowEnvCopy. |
401 | Invalid token/invitation, expired or revoked device. |
403 read_only | monitor scope; use an invitation with the required permissions. |
403 local_only | Manage invitations through server localhost. |
403 origin_denied | Check address, port, and origin preservation in the proxy. |
| No network access | Check bind, IP, firewall, port, and WSL connectivity. |
| No microphone | Grant permission; use localhost or remote HTTPS. |
| Slow/failed transcription | Check model download, memory, selected model, and audio format. |
| Media installation fails | Check internet, npm global prefix, and permissions; authenticate afterward. |
| No Companion summary | Check Ollama endpoint, service, model/tag, and enablement. |
| DSH unavailable | Check entrypoint, isolated directory, and separation from ~/.dsh. |
| Browser tests fail to launch | Install Playwright Chromium and required Linux libraries. |
Investigate with --log-level debug and /api/health. Remove secrets from logs before sharing.