When something breaks, run qorven doctor first. It checks DB, gateway, providers, channels, TLS, file perms, disk space, and config validity. If doctor is green and you still have an issue, this page is the playbook.

​
The five-minute diagnosis

1

Is the gateway alive?

sudo systemctl status qorven
curl -k https://localhost/health
# expected: {"status":"ok","version":"..."}
2

Is Postgres reachable?

sudo -u postgres psql -c "SELECT 1;"
qorven doctor
3

Are provider keys valid?

qorven providers verify openai
Hits the provider with a 1-token ping. If it fails, your key is wrong or expired.
4

Is the failure recent?

journalctl -u qorven -f --since "10 minutes ago"
Most real errors show up here with ERROR prefix.
5

Is a channel stuck?

qorven channels status
Every binding shows active / rate-limited / disconnected.

​
Log locations

SourceWhere
Gateway (systemd)journalctl -u qorven
Gateway (file)/var/log/qorven/gateway.log
Channels/var/log/qorven/channels.log
Install/var/log/qorven/install.log
Dockerdocker compose logs qorven
Tool runsqorven logs --filter tool
Agent loopqorven logs --filter agent.loop
Audit (human)Web UI → Audit
Audit (file)/var/log/qorven/audit.jsonl

​
Common failure modes

Mostly a config issue. Check journalctl -u qorven --since "1 minute ago" -e. Look for panic: chi: all middlewares must be defined before routes on a mux → see boot fails →.
Provider keys exhausted. Check Usage → Provider keys. Add a new key or switch to a different provider. If you’re on a free tier, you may have hit daily quota.
Local CA not trusted on this laptop. Run sudo qorven tls install-ca once on each browser host. TLS guide →
Either the provider can’t reach your public URL, or the signature check is failing. Look at /var/log/qorven/channels.log — each rejected webhook logs the reason. Common: webhook URL typo, expired signing secret, server behind NAT without port forward.
Usually LLM latency. qorven logs --filter llm.call shows per-call timing. If it’s the agent loop → check for tool timeouts (--filter tool.timeout).
Most likely: audit log. Set retention in config.toml:
[audit]
retention_days = 90
Or: Next.js build cache from an in-place dev install. rm -rf .next/.

​
Enable verbose logs temporarily

sudo systemctl set-environment QORVEN_LOG_LEVEL=debug
sudo systemctl restart qorven
# reproduce the issue
sudo journalctl -u qorven -f
# turn it off when done
sudo systemctl unset-environment QORVEN_LOG_LEVEL
sudo systemctl restart qorven

​
Dump diagnostics for support

qorven debug > /tmp/qorven-debug.txt
Collects: version, config (secrets redacted), DB migration status, provider verification, channel status, disk + memory usage. Share this in your GitHub Issue.

​
Where next

Log locations

Full file-system map of where things log.

Error codes

Every error string + cause.

Boot fails

Gateway refuses to start.

Getting help

Discord, issues, commercial.