Researched guidance: How should a D1 timeout with an uncertain write result be reconciled?

Summary

Treat a D1 write timeout or network error as an unknown outcome, not proof of failure. Make the logical write idempotent with a client-generated operation ID enforced by a UNIQUE or PRIMARY KEY constraint, reconcile with a read by that ID, and retry only the same idempotent operation when the documented error is retryable. Do not blindly replay non-idempotent writes.

Candidate action

For each logical mutation, generate a stable operation_id and persist it in a UNIQUE/PRIMARY KEY column on the affected record or an idempotency ledger. Use a prepared deterministic INSERT ... ON CONFLICT(operation_id) DO NOTHING/DO UPDATE, or an equivalent idempotent predicate; when several changes must commit together, issue them through one D1Database.batch() transaction. After a timeout or connection error, first query by operation_id. If present, treat the operation as committed and do not replay it. If absent and the error is documented as retryable, replay the identical idempotent operation with exponential backoff and jitter, then reconcile again. If the error is the storage-timeout/reset case, optimize, split, or shard the write and leave the original outcome unknown until reconciliation; do not assert that it rolled back or committed.

Applicability

• Cloudflare D1 Worker Binding API, including D1Database.run()/prepare() writes and D1Database.batch() transactions; adapt the schema to the application's logical operation key.
• Useful when the client sees Network connection lost, Replica disconnected from primary, Cannot resolve D1 DB due to transient issue on remote node, or a request-stream disconnect after a write may have been sent.
• For read replication and cross-request reconciliation, use D1 Sessions with first-primary for the first reconciliation read, then carry session.getBookmark() into later sessions.

Procedure

• Generate an operation_id before sending the mutation; never generate a new ID when retrying the same logical operation.
• Add a UNIQUE or PRIMARY KEY constraint for that operation ID and make the mutation deterministic with SQLite UPSERT semantics. If multiple writes must be atomic, put the idempotency record and business changes in one D1Database.batch() call.
• On any client timeout or network error, record the state as unknown and run a read-only SELECT by operation_id. Use withSession("first-primary") when read replication is enabled and preserve getBookmark() across requests.
• If the operation is found, return the existing result or a safe already-applied response; do not repeat the business mutation or trigger an external side effect twice.
• If it is not found and the error is documented as retryable, retry the identical idempotent statement with bounded exponential backoff and jitter, then reconcile. For the storage-operation-exceeded-timeout/reset error, first reduce query size, send fewer requests, or shard the work rather than blindly retrying.
• Keep the final state unknown when reconciliation and bounded retries cannot establish whether the write occurred; alert or queue manual reconciliation instead of emitting a PASS/FAIL conclusion.

Key findings

• Retrying a failed D1 operation is only safe when the query is idempotent; Cloudflare recommends application-level checks before retrying. (S1)
• D1 automatic retries are limited to read-only queries containing SELECT, EXPLAIN, or WITH; write-causing queries are not automatically retried. (S1)
• Cloudflare lists Network connection lost, Replica disconnected from primary, and transient remote-node resolution errors as retryable, while the storage-operation-exceeded-timeout/reset error calls for optimizing, reducing requests, or sharding. (S1)
• D1Database.batch executes statements sequentially in one SQL transaction and aborts or rolls back the sequence if a statement fails; D1 Sessions bookmarks preserve sequential consistency across sessions. (S3)
• SQLite UPSERT can turn a UNIQUE/PRIMARY KEY conflict into DO NOTHING or DO UPDATE, providing a standard mechanism for using the same operation key on retry. (S5)
• D1's maximum SQL query duration is 30 seconds, and that limit applies to the entire batch call. (S4)

Known limitations

• Cloudflare's public D1 guidance recommends idempotent retries but does not promise a universal commit point or a definitive committed/rolled-back result for every client-visible timeout; the read-by-operation-ID pattern is application-level reconciliation.
• D1 automatically retries read-only queries safely, while write-causing queries are not automatically retried. Application retries of writes are only safe when the business operation is idempotent.
• The documented maximum SQL query duration is 30 seconds and applies to an entire batch call; large writes should be split, but splitting changes transaction boundaries and must be designed explicitly.
• A D1 batch is atomic for its statements, but this does not make a separate external API call atomic with the database. No live database, Worker, or timeout was executed in this research cycle.

Obsolete approaches

• Blindly replaying a non-idempotent INSERT, UPDATE, or side effect after a timeout or Network connection lost error.
• Treating a client-visible timeout as proof that the write did not commit, or as proof that it committed, without a reconciliation read.
• Assuming D1 automatic retry behavior applies to write queries.

Negative results

• Cloudflare's Debug D1 documentation gives retry guidance for several network errors but does not define a universal commit/rollback outcome for a write whose client connection timed out.
• For the exact storage operation exceeded timeout which caused object to be reset error, Cloudflare recommends optimizing, reducing request volume, or sharding rather than an unconditional retry.
• D1 metadata such as rows_written and changed_db is useful when a response is received, but the public documentation does not describe it as a reconciliation mechanism after a missing response.

Evidence boundary

• basis=researched_guidance from public Cloudflare and SQLite documentation; executed=false; independent_reproduction=false.
• The sources establish retry recommendations, D1 batch/session semantics, and SQLite UPSERT behavior. They do not establish what happened in any particular timed-out request, database, Worker version, query, or network path.
• Do not record a PASS/FAIL outcome from this web research.

What remains unknown

• Whether a particular timed-out D1 write committed before the client lost its response remains unknown until an operation-ID reconciliation read finds the effect or a bounded retry establishes it.
• Cloudflare does not document a universal commit-point or response-loss protocol for all D1 write timeouts, overloads, resets, and request disconnects.
• Behavior may vary with the exact D1 API path, query shape, runtime, database storage version, query size, and read-replication configuration; inspect the actual environment.
• The application must define whether a duplicate operation returns the prior result, performs a deterministic update, or requires manual review.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Debug D1 — Cloudflare D1 documentation · official_documentation · accessed 2026-09-27
• S2 Retry queries — Cloudflare D1 documentation · official_documentation · accessed 2026-09-27
• S3 D1 Database Worker Binding API — Cloudflare D1 documentation · official_documentation · accessed 2026-09-27
• S4 Limits — Cloudflare D1 documentation · official_documentation · accessed 2026-09-27
• S5 UPSERT — SQLite documentation · standard · accessed 2026-09-27