Troubleshooting

Common owlcoda doctor warnings, install snags, and config mistakes — what they mean and how to fix them.

When something doesn’t work, owlcoda doctor is the first step. It checks Node version, the local runtime, the proxy port, and every configured model.

”Local runtime: not reachable” warning (Day 0)

What it means: No local backend is listening on the URL in your config.json routerUrl.

Fix: Start one of: Ollama (ollama serve), LM Studio’s local server, or vLLM (vllm serve …). Then rerun owlcoda init to auto-detect it. Or set --router explicitly:

owlcoda init --router http://127.0.0.1:11434/v1

This warning is intentionally not a hard failure — Day 0 you’re allowed to install OwlCoda before any backend.

”Models: 0/N healthy” warning

What it means: Either the runtime isn’t reachable (see above) or the configured model id doesn’t match what the backend actually serves.

Fix: Run owlcoda models to compare configured vs visible models. If they differ, edit config.json so backendModel matches what the backend reports.

What it means: Your global npm prefix is not writable. See Install / If npm link fails for three workarounds.

Port 8019 already in use

What it means: Another OwlCoda daemon is running, or a different process holds the port.

Fix:

owlcoda status              # check if it's our daemon
owlcoda stop --force        # stop the daemon
lsof -i :8019               # if not us, find who

Or change OwlCoda’s port:

OWLCODA_PORT=8020 owlcoda

“SearXNG not reachable” warning

What it means: OwlCoda’s optional WebSearch tool needs SearXNG. If you don’t use web search, ignore this.

Fix (only if you want web search): Install SearXNG locally, set OWLCODA_SEARXNG_URL=http://localhost:8888, restart OwlCoda.

Training data accidentally enabled

What it means: OWLCODA_TRAINING_COLLECTION=1 was set in your shell, or trainingCollection: true in config.json.

Fix: Unset and clear what was already collected:

unset OWLCODA_TRAINING_COLLECTION
# in config.json, set "trainingCollection": false
owlcoda training clear

Where do my sessions live?

ls -la ~/.owlcoda/sessions/

Backup or delete at will. Sessions are JSON; owlcoda sessions --json reads them.

Still stuck