Solución de problemas

Cuando algo se sienta raro, ejecuta korva doctor primero. Verifica 13+ invariantes y devuelve una remediación clara para cada fallo. La mayoría de los problemas a continuación también los reporta korva doctor.

”Vault no está corriendo”

korva vault status
korva vault start
korva doctor

Si vault start falla con un error de puerto en uso, hay otra cosa en :7437:

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

También puedes elegir un puerto distinto:

KORVA_VAULT_PORT=7438 korva vault start

Recuerda actualizar la config de tu IDE para que coincida.

El IDE no detecta las herramientas de Korva

korva setup --all
korva doctor

korva setup es idempotente y solo sobrescribe la entrada MCP de korva-vault — nunca toca claves no relacionadas en tu config. Tras ejecutarlo, reinicia el IDE por completo (algunos IDEs cachean los servidores MCP por sesión).

Si el IDE sigue sin ver las herramientas:

1. Verifica que la entrada MCP existe en el archivo de config correcto (la página de Integraciones lista cada ruta).
2. Confirma que korva-vault está en el $PATH del IDE — algunos IDEs arrancan con un entorno reducido.
3. Ejecuta korva-vault mcp manualmente en un terminal — debería quedarse esperando stdin. Si falla, el error te dice por qué.

”database is locked” al guardar

Esto suele significar que una consulta de larga duración está manteniendo un lock de escritura y SQLite alcanza el busy timeout. Korva ejecuta SQLite en modo WAL con busy_timeout=5000 precisamente para minimizar esto, pero un vault_search de varios segundos sobre una BD enorme puede aún dispararlo.

Workarounds:

• Reduce el alcance de la búsqueda: vault_hint en lugar de vault_search, o pasa limit=10.
• Ejecuta korva vault clean para deduplicar. La mayoría de vaults se reducen ~30 % la primera vez.
• Si importas una gran cantidad de data, define KORVA_VAULT_BUSY_TIMEOUT=30000 para esa sesión.

La licencia dice “expired” pero acabo de pagar

korva license status

Si el heartbeat aún no ha corrido:

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

El Vault re-verifica en cada arranque, pero el heartbeat solo corre cada 24 h por sí solo. Re-activar lo fuerza.

Si el endpoint de licencias no es alcanzable (red corporativa), la instalación corre en modo gracia (default 7 días) con todas las features de Teams. Tras expirar la gracia, degrada con normalidad a Community sin borrar datos.

”admin.key: permission denied”

Siempre verifica que el modo del archivo sea 0600:

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

Si generas admin.key desde un terminal con un umask incorrecto, esto puede quedar como 0644 y el Vault se niega a cargarlo.

korva setup vscode dice “VS Code not found”

korva setup busca el binario del editor vía which. Si tu VS Code vive en una ruta no estándar, pásala explícitamente:

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

El worker de Hive dice disabled pero lo quiero on

korva hive enable
korva hive status

Si el estado sigue diciendo disabled, la variable de entorno kill-switch está definida en algún lado:

echo $KORVA_HIVE_DISABLE  # debería estar vacía

Quítala (o elimínala del rc de tu shell) y reinicia el Vault.

Backups

La BD del Vault vive en ~/.korva/vault/observations.db. Para tomar un backup en caliente:

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

VACUUM INTO es seguro bajo WAL — no bloquea a los escritores.

Reinstalar desde cero

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

Tus datos antiguos están en ~/.korva.bak.* por si necesitas recuperar observaciones específicas.

Reportar un bug

Si korva doctor no ayuda, abre un issue con la salida de:

korva --version
korva doctor
korva vault logs   # luego tail -50 sobre la ruta impresa

Issues en https://github.com/AlcanDev/korva/issues.

Para problemas de seguridad, usa GitHub Security Advisories en su lugar — confirmamos en 48 horas.