Troubleshooting
Database Problems
Check SQLite consistency, locks, migrations and recovery state.
Stop writes and make a filesystem copy before diagnosis. Kaya uses /app/data/kaya.db plus possible WAL/SHM files and creates kaya.db.pre-migration before normal startup migration.
docker compose stop kaya secure-send-gateway
cp -a data "data-diagnostic-$(date +%F-%H%M%S)"
docker compose start kaya secure-send-gateway
docker compose logs --tail=250 kaya
database is locked can indicate a long transaction, abrupt termination, filesystem locking problem or multiple replicas. Run one application instance. Integrity/malformed errors require restore or SQLite specialist recovery; migration errors require the exact application version and preceding log.
Do not replace .runtime.env while testing a database. See Restoring Kaya.