Repository navigation
Troubleshooting
Only entries that have actually happened in this repository are listed.
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.
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.
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.
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.
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.
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.
Intentional. In the sqld flavor, syncInterval: 0 disables automatic
background sync; manual DB::sync() still works.
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.