Turso libsql connection failed (URL or auth token) in CI

By Daniel Zoghalchali·Latchkey

Connecting to Turso from an app needs two things: the libsql:// database URL and a database auth token. In CI, a missing token, an expired token, or the wrong URL scheme causes the libsql client to fail before any query runs.

What this error means

A libsql client fails with "auth token required", "unauthorized", or "unsupported URL scheme" when connecting to a Turso database from a test step.

LibsqlError: SERVER_ERROR: Server returned HTTP status 401
(auth token missing or expired for libsql://pr-123-my-org.turso.io)

Common causes

No auth token supplied to the client

The libsql URL alone is not enough; without a database auth token the server returns 401.

The wrong URL scheme or a stale token

Using an http URL where libsql:// is expected, or a token that expired, breaks the connection.

How to fix it

Mint a token and pass both URL and token

1. Create a database auth token at CI time.
2. Read the libsql:// URL for the database.
3. Pass both to the libsql client.

URL=$(turso db show "pr-${{ github.event.number }}" --url)
TOKEN=$(turso db tokens create "pr-${{ github.event.number }}")
echo "TURSO_DATABASE_URL=$URL" >> "$GITHUB_ENV"
echo "TURSO_AUTH_TOKEN=$TOKEN" >> "$GITHUB_ENV"

Configure the client with the token

Give the libsql client the URL and auth token explicitly so it authenticates the connection.

import { createClient } from '@libsql/client';
const db = createClient({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

How to prevent it

• Always pass an auth token alongside the libsql URL.
• Mint a fresh token per run rather than reusing an expired one.
• Use the libsql:// scheme the client expects, not a plain http URL.

Frequently asked questions

Related guides

References

• GitHub Actions documentation