Skip to content

Help

libSQL and DuckDB errors and how to fix them

Tested with:Databasezy API v1 · zb CLI 0.1

libSQL / SQLite and DuckDB are both available on every plan, including Free. Both are reached over HTTPS only: libSQL with an auth token (Authorization: Bearer), DuckDB with HTTP Basic authentication as user app and the generated password. Neither has a wire protocol you can open with sqlite3, psql or another shell.

The connection closes during the TLS handshake

Section titled “The connection closes during the TLS handshake”

Cause: the gateway closes the connection without an HTTP response in these cases:

  • the client used http:// instead of https://
  • the client connected by IP address, so no TLS server name was sent
  • your address is not on the allow-list
  • your address is temporarily blocked after repeated failed logins

Fix: use the https:// host from the Connect tab, and add your egress CIDR under Network → IP allow-list. HTTP engines use port 443 (8443 in single-IP regions), and the Connect tab shows which one. See IP allow-lists.

503 with {"error": "paused"} or a “waking up” message

Section titled “503 with {"error": "paused"} or a “waking up” message”

Cause: with a “waking up” message, a sleeping Free instance is waking: Free instances sleep after 15 minutes without connections, and the gateway holds the first request for up to 30 seconds while the instance wakes. These engines can take a little longer than that to resume, so the first request after a sleep can fail. With {"error": "paused"}, someone paused the instance on purpose (or support did, as the message says), and requests never wake it.

Fix: after a sleep, retry the request. For a pause, run zb instances resume <instance_id> (support pauses need support). Run zb instances resume <instance_id> before batch jobs on Free instances too. See Paused and waking instances.

429 with too_many_connections or rate_limited

Section titled “429 with too_many_connections or rate_limited”

Cause: you reached the size’s connection limit, or opened more than 50 new connections in one second.

Fix: reuse HTTP connections (keep-alive), and retry after the Retry-After header.

Cause: the server accepts auth tokens only (authToken in the libSQL clients, sent as Authorization: Bearer); HTTP Basic authentication is refused. A token also stops working when it expires (60 s of clock allowance), when it was minted for another instance, and after a credential rotation (the server restarts with a new key).

Fix: reveal the current token with zb instances credentials reveal <instance_id> (token), or mint a new scoped one with zb instances tokens create <instance_id>, and pass it as authToken.

A write fails with “not authorized” while reads work

Section titled “A write fails with “not authorized” while reads work”

Cause: the token is read-only (minted with --read-only).

Fix: use the revealed token or mint a full-access token (zb instances tokens create <instance_id> --ttl 1h).

Cause: SQLite allows one write transaction at a time. A long write transaction makes other writers wait or fail.

Fix: keep write transactions short and retry on busy errors. Readers are not blocked.

Cause: embedded replicas need sqld’s replication endpoint, which Databasezy does not expose. This feature is not available.

Fix: read and write through the HTTPS endpoint.

Cause: the database file reached the size’s storage limit. On the Free size, that limit is 1 GB.

Fix: delete data and run VACUUM, or grow storage. See Resize.

Cause: the SQL failed, the JSON body was invalid, or sql was empty. The error field carries DuckDB’s message.

Fix: send {"sql": "...", "params": [...]} to POST /query. params is optional and binds to ? or $1.

Cause: missing or wrong Basic credentials. Every path except /health needs them. After a rotation, the server restarts and the old password stops working.

Fix: reveal the current password and send Authorization: Basic base64(app:<password>).

Cause: request bodies are limited to 1 MiB.

Fix: split large inserts into batches.

Cause: a response carries at most 10,000 rows. The rest are dropped.

Fix: aggregate in SQL, or page with LIMIT and OFFSET.

Cause: all requests share one DuckDB connection and run one at a time. There is no per-query timeout and no cancellation, so one long query holds up everything behind it. Transaction state is also shared, so BEGIN and COMMIT in separate requests do not work.

Fix: keep queries short and treat every request as autocommit. For many concurrent users, use ClickHouse.

Cause: the PostgreSQL wire protocol is not implemented for DuckDB yet. Only the HTTPS API is available.

Fix: use the HTTPS API. See DuckDB.

The instance restarts during a large query

Section titled “The instance restarts during a large query”

Cause: big sorts, joins and aggregations spill to a small temporary area. They can also exceed the size’s memory. In both cases the instance restarts.

Fix: reduce the query’s working set, or resize.

Neither engine has point-in-time recovery. A restore returns to the state of one backup. See Restore a backup.

Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket) and include:

  • the instance id, engine and region
  • the HTTP status and the error body
  • the request path
  • your client library and its version
  • the time of the failure in UTC

Never paste passwords, connection strings with passwords, API keys or patient data (PHI) into a ticket. See How to get help.