Newly-created Cloud DB returns `SERVER_ERROR: Server returned HTTP status 404` for ~2.5s after the Platform API reports it exists (create→serve gap, no readiness signal)

[ejc3]

Summary

A query to a freshly-created Turso Cloud database throws LibsqlError: SERVER_ERROR: Server returned HTTP status 404 for ~2.5 seconds after the Platform API has acknowledged the create and the control plane reports the database as existing. There is no readiness signal to wait on, and the 404 is byte-identical to the one a database that never existed returns — so it's indistinguishable from "database not found".

This is the natural sequel to #189 ("Confusing error message when database URL does not exist"): the same 404 is also returned for a database that does exist but whose libSQL endpoint isn't serving yet.

The root cause looks platform-side (control plane vs. data plane), but it surfaces entirely through @libsql/client, and there's a concrete client-side ask below, so filing here — happy to move if there's a better tracker.

Environment

• @libsql/client 0.17.3, Node v22.22.0
• Turso Cloud, database-per-database in a group (created via Platform API POST /v1/organizations/{org}/databases)
• Reproduced both in-region (Vercel iad1 ↔ aws-us-east-1 group) and cross-region (see Region below)

The error

LibsqlError: SERVER_ERROR: Server returned HTTP status 404
  (cause: HttpServerError, status 404)

Reproduction

Minimal, self-contained, secrets-free: https://github.com/ejc3/turso-create-serve-404

npm install
TURSO_API_TOKEN=… TURSO_ORG=… TURSO_GROUP=… TURSO_GROUP_AUTH_TOKEN=… node repro.mjs

For each fresh db it samples both planes against one clock, and queries the data plane both at control-exists (data@control) and after the create POST returned 200 to the caller (data@post-ack). Reproduces 6/6–10/10 every run; each db is deleted afterward:

baseline: data-plane query to a NEVER-created db → 404  (same HTTP 404 as the create→serve case)

# 1 reprotest-a483aa0d: POST-ack@465ms | control "exists"@144ms → data@control=404 | data@post-ack=404 | data serves@2504ms | gap=2360ms  ← create→serve 404
# 2 reprotest-ec2257b2: POST-ack@399ms | control "exists"@124ms → data@control=404 | data@post-ack=404 | data serves@2458ms | gap=2334ms  ← create→serve 404
# 4 reprotest-f2b422cc: POST-ack@326ms | control "exists"@226ms → data@control=404 | data@post-ack=404 | data serves@2447ms | gap=2221ms  ← create→serve 404
...
RESULT: 6/6 reproduced the create→serve 404 (data plane 404'd at control-exists and/or after POST-ack, AND the db later served)
gap (control "exists" → data serves): min=2189ms median=2342ms max=2360ms

A reproduction is counted only when the data plane 404s and the same database later serves — so wrong credentials / permanent unavailability cannot be a false positive.

Mechanism (and why it is NOT a client read-before-write)

Sampling both planes from one t0 (just before the create POST):

signal	when
control plane GET /databases/{name} first returns 200 ("exists")	~75–230ms
POST /databases returns 200 to the caller (create ACKed)	~260–470ms
a data-plane SELECT 1 at the instant the control plane said "exists" (data@control)	404
a data-plane SELECT 1 after the POST returned 200 to the caller (data@post-ack)	404
the data-plane endpoint first actually serves	~2.4–2.6s
gap (control "exists" → data serves)	~2.2–2.5s

Two independent witnesses rule out "the client queried before its write landed":

1. data@control runs after the control plane confirmed the db exists — Turso has durably registered the create — yet the data plane 404s.
2. data@post-ack runs after POST /databases returned 200 to the caller — the write call has demonstrably completed for the client — and it still 404s for ~2s more.

In both cases the same hostname + same credentials 404s and then serves with no change on the caller's side. That is a control→data serve/propagation gap inside Turso.

And per the baseline line: a query to a never-created database returns the same HTTP 404, so the error alone can't distinguish "not ready yet" from "doesn't exist" (cf. #189).

Region

• Cross-region (client outside the group's region): gap ~2.2–2.5s (table above).
• In-region (Vercel iad1 against an aws-us-east-1 group): the control plane reports "exists" within ~20ms; the gap is shorter but still reliably hit — a fan-out of cold readers that connect at the "exists" signal saw 62/80 queries 404 across 7/8 fresh databases in iad1.

The window exists in- and cross-region; it's merely larger the farther the reader is from the group.

Impact

The database-per-tenant / per-session / per-agent pattern (which Turso Cloud is marketed for) creates a fresh database on the hot path. Any reader that connects based on the control plane's "exists" signal — a separate process, a cold serverless instance, a second request — lands in this window and 404s on the first query of a brand-new database.

Suggested fixes (any one helps)

1. A readiness signal — expose database status (provisioning → ready) on the Platform API, or don't let GET /databases/{name} return 200 until the data-plane endpoint serves.
2. Make the not-ready response unambiguous — return a distinct, retryable status/code (e.g. 425/409/a provisioning error) instead of a bare 404 that collides with "does not exist". (This part is actionable in @libsql/client: surface a distinct error type for the not-ready/404 case so callers can retry without string-matching.)
3. Make POST /databases not ACK until the endpoint serves (synchronous create), so create completion is the readiness signal.

Current workaround

After opening a connection to a freshly-created database, probe SELECT 1 with bounded exponential backoff, retrying only the 404 / unresolved-host transients, before treating the connection as usable. It reliably absorbs the window — but it's a guess at an opaque, unbounded delay that a readiness signal would make unnecessary.

[ejc3]

Update: real CI failure exceeded the 15-second readiness window

I hit the same create→serve race in a real Vercel-preview CI run on 2026-08-23, but this time the newly-created database endpoint was still returning 404 after our entire 15,000 ms bounded readiness window—not merely ~2.5 seconds.

Environment:

• @libsql/client 0.17.3
• @libsql/hrana-client 0.10.0
• Turso group region: aws-us-east-1
• Vercel deployment: dpl_GQPLJ8aUHQmYEKeC7n6eF1vYWiuF
• application commit: ff5a3929b772a1b9486d3c5b78a2038135879d6b
• failed GitHub Actions attempt

Two independent requests to the freshly-created database both exhausted 6 probes over 15 seconds and returned application HTTP 500 because every underlying libSQL probe failed with:

LibsqlError: SERVER_ERROR: Server returned HTTP status 404
cause: HttpServerError
status: 404
extendedCode: undefined
rawCode: undefined

Exact invocation evidence from the deployed function logs:

UTC invocation time	stable application invocation ID	Turso/libSQL result
2026-08-23T12:03:19.601Z	tnstq-1787486599601-6253f595b3ea	6× 404; 15,000 ms window exhausted
2026-08-23T12:03:36.136Z	d8cdz-1787486616136-7f6ca0c42cd9	6× 404; 15,000 ms window exhausted

The corresponding tests took 16.663 s and 15.856 s, respectively.

There are two useful controls:

1. Cleanup immediately afterward successfully deleted exactly the two databases created by this run, and reported zero remaining test databases. A second cleanup pass deleted zero. So the control-plane creates existed; these were not queries to misspelled/nonexistent resources.
2. An unchanged rerun of the same commit/deployment passed completely. Fresh database calls in that run needed only one readiness retry. That makes a deterministic application/configuration error very unlikely and is consistent with an unusually long control→data-plane propagation event.

Trace/request IDs

Unfortunately there is no Turso trace ID available in the surfaced error:

• both deployed-function log records have traceId: "";
• HttpServerError exposes only message and status;
• @libsql/hrana-client's HTTP error construction discards response headers, so even if the 404 response carried a provider request ID, the application cannot recover/log it.

The stable invocation IDs and exact UTC timestamps above are therefore the best correlation coordinates available from the caller side. This incident strengthens the original report in two ways: the readiness gap can exceed 15 seconds, and current client error plumbing prevents callers from preserving a provider request ID for support correlation.

[ejc3]

API surface used by the affected deployment

To make the two August 23 incidents easier to correlate, here is the exact control-plane/data-plane request sequence used by application commit ff5a3929b772a1b9486d3c5b78a2038135879d6b.

Control plane — Turso Platform REST API

The application calls the Platform API directly with fetch (not through the Turso CLI or a database-management SDK):

POST https://api.turso.tech/v1/organizations/{org}/databases
Authorization: Bearer {organization-scoped Platform API token}
Content-Type: application/json

{"name":"{databaseName}","group":"{groupName}"}

The normal create path accepts a successful response (or 409 for an idempotent concurrent create). Only a 400/422 conflict-shaped response invokes this existence check:

GET https://api.turso.tech/v1/organizations/{org}/databases/{databaseName}
Authorization: Bearer {organization-scoped Platform API token}

That GET is an idempotency fallback, not a readiness gate: as the original reproduction shows, control-plane existence does not imply that the data-plane endpoint is serving.

The post-failure cleanup control used GET .../databases to list and DELETE .../databases/{databaseName} to remove the two test databases. Those list/delete calls are not part of the create→serve hot path.

Data plane — @libsql/client / Hrana over HTTP

After the create acknowledgement, the application constructs:

createClient({
  url: "libsql://{databaseName}-{org}.turso.io",
  authToken: groupToken,
});

and probes readiness with:

await client.execute("SELECT 1");

With the exact installed versions from the incident (@libsql/client 0.17.3 and @libsql/hrana-client 0.10.0), that libsql: URL uses the HTTP client and the probe is sent as an authenticated Hrana v2 pipeline request:

POST https://{databaseName}-{org}.turso.io/v2/pipeline
Authorization: Bearer {group token}
Content-Type: application/json

The six 404s in each failed invocation surfaced from this data-plane client.execute("SELECT 1") loop. This path does not use WebSockets, embedded-replica sync, the Turso CLI, or the Vercel integration's single-database TURSO_DATABASE_URL / TURSO_AUTH_TOKEN; it uses an organization Platform token for provisioning and a group token for all per-session database connections.

No credential value, database token, or raw session identifier is included here. As noted above, the client also did not expose any response/request/trace header from the 404 responses.