Troubleshooting

When something feels off, run korva doctor first. It checks 13+ invariants and prints a clear remediation for each failure. Most issues below are also reported by korva doctor.

”Vault is not running”

korva vault status
korva vault start
korva doctor

If vault start fails with a port-in-use error, something else is on :7437:

# macOS / Linux
lsof -i :7437
# Windows
netstat -ano | findstr 7437

You can also pick a different port:

KORVA_VAULT_PORT=7438 korva vault start

Remember to update your IDE config to match.

IDE doesn’t pick up Korva tools

korva setup --all
korva doctor

korva setup is idempotent and overwrites only the korva-vault MCP entry — it never touches unrelated keys in your config. After running it, fully restart the IDE (some IDEs cache MCP servers per session).

If the IDE still doesn’t see the tools:

1. Check the MCP entry exists in the right config file (the Integrations page lists every path).
2. Confirm korva-vault is on the IDE’s $PATH — some IDEs launch with a stripped environment.
3. Run korva-vault mcp manually in a terminal — it should sit waiting for stdin. If it errors out, the error tells you why.

”database is locked” on save

This usually means a long-running query is holding a write lock and SQLite hits the busy timeout. Korva runs SQLite in WAL mode with busy_timeout=5000 precisely to minimise this, but a multi-second vault_search over a giant DB can still trigger it.

Workarounds:

• Reduce the search scope: vault_hint instead of vault_search, or pass limit=10.
• Run korva vault clean to deduplicate. Most vaults shrink ~30 % the first time.
• If you import a large amount of data, set KORVA_VAULT_BUSY_TIMEOUT=30000 for that session.

License says “expired” but I just paid

korva license status

If the heartbeat hasn’t run yet:

KORVA_LICENSING_ENDPOINT=https://licensing.korva.dev korva license activate <key>

The Vault re-verifies on every startup, but the heartbeat only runs every 24 h on its own. Re-activating forces it.

If the licensing endpoint is unreachable (corporate network), the install runs in grace mode (default 7 days) at full Teams features. After the grace period expires it gracefully degrades to Community without deleting any data.

”admin.key: permission denied”

Always check the file mode is 0600:

ls -l ~/.korva/admin.key
chmod 0600 ~/.korva/admin.key

If you generate admin.key from a terminal that ran with the wrong umask, this can become 0644 and the Vault refuses to load it.

korva setup vscode says “VS Code not found”

korva setup looks up the editor binary via which. If your VS Code lives in a non-standard path, pass it explicitly:

korva setup vscode --binary "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code"

Hive worker says disabled but I want it on

korva hive enable
korva hive status

If the status still says disabled, the kill-switch env var is set somewhere:

echo $KORVA_HIVE_DISABLE  # should be empty

Unset it (or remove it from your shell rc) and restart the Vault.

Backups

The Vault DB lives at ~/.korva/vault/observations.db. To take a hot backup:

sqlite3 ~/.korva/vault/observations.db "VACUUM INTO '/tmp/korva-backup.db'"

VACUUM INTO is safe under WAL — it doesn’t lock writers.

Reinstalling from scratch

korva vault stop
mv ~/.korva ~/.korva.bak.$(date +%s)
korva init
korva setup --all
korva vault start

Your old data is in ~/.korva.bak.* if you need to recover specific observations.

Reporting a bug

If korva doctor doesn’t help, please open an issue with the output of:

korva --version
korva doctor
korva vault logs   # then tail -50 the printed path

Issues live at https://github.com/AlcanDev/korva/issues.

For security issues, please use GitHub Security Advisories instead — we acknowledge in 48 hours.