Skip to content

Troubleshooting

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

Troubleshooting

Connection refused / could not resolve host

sqld is not running or the URL is wrong. For local development:

docker run --name libsql-test-sqld -p 8081:8080 ghcr.io/tursodatabase/libsql-server:latest

Then use DB_URL=http://127.0.0.1:8081 and a token (see Configuration).

"SQLite error: no such table: …"

  • The test suite seeds itself at bootstrap — you don't need to do anything special (composer install && ./vendor/bin/pest).
  • With TURSO_HTTP_SKIP_SEED=1, or in your own app, the database is whatever you point DB_URL at — the package does not create tables automatically.
  • In Laravel, make sure your migrations ran; this package is only the client, not a migration runner.

401 / 403 / token errors from Turso Cloud

  • The token expired (Turso Cloud tokens are JWTs — check exp).
  • The URL points at the wrong database (libsql://<db>-<org>.turso.io).
  • A local-only test token is being used against Turso Cloud (or vice versa) — those are different authorities.
  • The library throws LibSQLError with the server's message for these — if you are catching nothing, the exception text tells you which case it was.

Turso Cloud: /version returns HTTP 404

GET /version exists only on self-hosted libsql-server (sqld). Against Turso Cloud, LibSQL::version() throws a catchable LibSQLError (HTTP 404: route not found: ["version"]). To check live connectivity from cloud, use the pipeline:

$v = $db->query('SELECT sqlite_version() AS v')->fetchArray(
    \Darkterminal\TursoHttp\LibSQL::LIBSQL_ASSOC
)[0]['v'];

Facade throws "Class not found" / provider missing

php artisan package:discover
php artisan optimize:clear

If you published the config earlier with different keys, republish with --tag=turso-http-config and re-check config/turso-http.php.

Tests fail with empty data / “no such table” in CI

CI provisions a seeded sqld service container and the suite seeds itself — if you see this, your DB_URL is pointing somewhere other than the service container (e.g. host.docker.internal from inside the same host), or TURSO_HTTP_SKIP_SEED=1 leaked into the environment.

DATETIME shows the raw value instead of converted time

Only exact Y-m-d H:i:s strings convert, and only when DB_TIMEZONE resolves to a known timezone. Otherwise the value is returned as stored.

Multiple LibSQL instances

The client creates a fresh curl handle per HTTP request (no connection pooling). It is safe to create multiple LibSQL instances, but in hot paths prefer one shared instance per process (e.g. Laravel's turso singleton) so you don't pay DSN parsing and object setup per query.

Clone this wiki locally