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.
Errors on both engines
Section titled “Errors on both engines”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 ofhttps:// - 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.
libSQL / SQLite
Section titled “libSQL / SQLite”401 Unauthorized on every request
Section titled “401 Unauthorized on every request”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).
SQLITE_BUSY or database is locked
Section titled “SQLITE_BUSY or database is locked”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.
Embedded replicas or syncUrl do not work
Section titled “Embedded replicas or syncUrl do not work”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.
Writes fail because the disk is full
Section titled “Writes fail because the disk is full”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.
DuckDB
Section titled “DuckDB”400 with {"error": "..."}
Section titled “400 with {"error": "..."}”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.
401 Unauthorized
Section titled “401 Unauthorized”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>).
413 “request body exceeds … bytes”
Section titled “413 “request body exceeds … bytes””Cause: request bodies are limited to 1 MiB.
Fix: split large inserts into batches.
"truncated": true in the response
Section titled “"truncated": true in the response”Cause: a response carries at most 10,000 rows. The rest are dropped.
Fix: aggregate in SQL, or page with LIMIT and OFFSET.
Requests queue up or time out
Section titled “Requests queue up or time out”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.
Connecting with a PostgreSQL client fails
Section titled “Connecting with a PostgreSQL client fails”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.
Restores
Section titled “Restores”Neither engine has point-in-time recovery. A restore returns to the state of one backup. See Restore a backup.
Still stuck?
Section titled “Still stuck?”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
errorbody - 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.