Skip to content

Troubleshooting

Imam Ali Mustofa edited this page Nov 10, 2026 · 2 revisions

Troubleshooting

Only entries that have actually happened in this repository are listed.

"Can not sync a database without a wal_index, please delete the database and attempt again"

Cause: local replica file exists from a previous run; or the migration which produces the server-side schema has not run yet on a fresh sqld.

Fix: delete the local replica file and retry; the harness always wipes its volumes. CI seeds sqld with a _boot table first so a brand-new server can build WAL metadata.

"server returned a conflict: sent=1, got=17"

Cause: writes made to a fresh local replica before the first sync(), or a stale WAL sidecar.

Fix: call DB::sync() on a fresh replica before any write. Delete the replica file before re-seeding.

"Unsupported driver [http]"

Cause: DB_SYNC_URL=http://host:port in .env — Laravel parses url: and uses the scheme as the driver.

Fix: use libsql://… for Turso Cloud URLs. For self-hosted sqld, use libsql://127.0.0.1:8080 with DB_SQLD_OFFLINE_MODE=true when relevant.

Writes silently dropped / false returned

Symptom: pre-1.4.0 the driver returned false for failed INSERT/UPDATE/DELETE instead of throwing.

Fix: upgrade to >= 1.4.0. Writes now throw PDOException.

Replica tests pass locally, fail in CI / vice versa

Cause: LocalRemoteReplicaTest and MultiConnectionTest share a running sqld; a crashed earlier run leaves stale files. CI wipes fresh.

Fix: docker rm -f libsql-test-sqld* && docker run … fresh server, or run docker/proof/proof.sh which always wipes volumes first.

Encryption config seems ignored

Symptom: DB_ENCRYPTION_KEY set but the database is still readable.

Fix: encryption_key only takes effect at database creation time; an existing unencrypted database cannot be made encrypted retroactively through this key. The file must not pre-exist.

syncInterval: 0 makes sync never happen

Intentional. In the sqld flavor, syncInterval: 0 disables automatic background sync; manual DB::sync() still works.

Text reads back as binary garbage (e.g. ¢r instead of the stored word)

Cause: driver ≤ 1.6.0 treated any string cell that was canonical, printable base64 as a double-encoded blob and decoded it twice — plain text like the Faker word bzwobkku turned into two garbage bytes.

Fix: upgrade to ≥ 1.7.0. Blob transport now writes an explicit libsqlblob: marker and plain alphabetic text is never double-decoded.