In a Cloudflare Queues consumer Worker that never calls ack(), when is a delivered batch acknowledged, and what makes it retry?
answer
- silence means success
- returned, resolved, waitUntil resolved
- a throw fails every message
- forEach does not await
basics
~20 sA Queues batch is acknowledged implicitly once queue() returns, its promise resolves and every ctx.waitUntil() promise resolves. If queue() throws or any of those promises rejects, the whole batch fails and every message in it is retried.
solid answer
~40 sWith no explicit calls, Queues acknowledges the batch as one unit: once `queue()` has returned, the promise it returned has resolved, and every promise passed to `ctx.waitUntil()` has resolved. If the handler throws, or that promise or a `waitUntil()` promise rejects, the whole batch counts as failed and **every** message is retried, up to the consumer's `max_retries` (3 by default), even the ones that were already handled. The trap is iteration: `batch.messages.forEach(async ...)` does not await its callbacks, so the handler returns at once, the batch is acknowledged while the work is still running, and a failed send is silently lost. Use `for...of` with `await`, or `await Promise.all(...)`.
go deeper
Recall the three conditions for the implicit acknowledgement and that a throw fails the whole batch. Say the default retry limit is 3.
Explain why Queues can only redo the whole batch without explicit calls: it sees one success or failure per invocation. Show the forEach trap and the two correct ways to await.
Point out that the default suits all-or-nothing work such as one transaction per batch, and is wrong when each message has its own side effect, such as sending an email.
Treat 'does this consumer rely on the implicit acknowledgement' as a review checklist item: floating promises and batch-wide throws are where duplicate side effects and lost messages come from.
A **Cloudflare Queues consumer** is a Worker whose default export has a `queue(batch, env, ctx)` handler. Queues pushes a **batch** of messages to it, and the handler decides, explicitly or by default, what happens to each one. This deep dive covers the default: what happens when the handler never calls `ack()` or `retry()` at all. ## The default: implicit acknowledgement Queues treats the batch as one unit when the handler makes no explicit calls. The whole batch is acknowledged, meaning removed from the queue for good, once **all** of these are true: 1. The `queue()` function has returned. 2. If it returned a promise (every `async` handler does), that promise has resolved. 3. Every promise passed to `ctx.waitUntil()` has resolved. So a handler that awaits its work and returns normally has acknowledged every message it was given, without writing a single acknowledgement line. This is why the simplest consumer you see in tutorials, a `for...of` loop over `batch.messages` with an `await` inside, is correct as far as it goes. ## What counts as failure The batch fails, as a whole, when any of these happens: - `queue()` throws synchronously. - The promise it returned **rejects**, for example because an awaited `fetch()` threw or your code did `throw new Error(...)`. - A promise passed to `ctx.waitUntil()` rejects. A failed batch is not lost. Every message in it is **retried**: redelivered in a later batch, according to the consumer's retry settings. The consumer setting `max_retries` defaults to **3**; once a message has used them up it is deleted, or written to the queue named in `dead_letter_queue` if one is configured. Each retry also counts as an extra read operation for billing. | Handler outcome | What Queues does with the batch | |---|---| | Returns, promise resolves, `waitUntil` work resolves | Every message acknowledged | | Throws, or its promise rejects | Every message retried | | A `ctx.waitUntil()` promise rejects | Every message retried | | Returns before the work it started has finished | Every message acknowledged, the unfinished work may never complete | ## Why the whole batch, and why that matters With no explicit calls, the only signal Queues receives is "this invocation succeeded" or "this invocation failed". It cannot tell that messages 1 to 7 of a ten-message batch were handled and message 8 threw, so it redelivers all ten. For an email consumer that is the dangerous part: the emails for messages 1 to 7 were already sent, and they will be sent again on the retry. The fix for that, per-message `ack()` and `retry()`, belongs to the explicit API; the point to take from the default is that **a throw is a batch-level verdict**. ## The async iteration trap The rule "acknowledged when `queue()` returns" has a sharp edge. `batch.messages.forEach(async (msg) => { ... })` starts an async callback for every message but does **not** wait for any of them: `forEach` ignores the promises its callback returns. The handler returns at once, its promise resolves, and the batch is acknowledged while the sends are still in flight. Work that has not finished when the handler returns may not complete at all, and a rejection inside one of those callbacks never fails the batch, so a failed send is silently dropped. The Queues docs call this out directly: iterate with `for (const msg of batch.messages)` and `await` inside, or collect the work with `await Promise.all(batch.messages.map(work))`. Both make the handler's promise wait for the work, so the implicit acknowledgement happens after it, and a failure fails the batch. The same reasoning applies to background tasks: anything that must finish after the main work, such as a metrics call, goes through `ctx.waitUntil()`, which the acknowledgement waits for; a promise that is neither awaited nor passed to `waitUntil()` does not hold the batch open. ## Where explicit calls come in The implicit model is fine when the batch really is all-or-nothing, for example a consumer that writes the whole batch in one database transaction. It is the wrong model when each message has its own side effect, which is the email case. There, the consumer calls `message.ack()` after each successful send and `message.retry()` for a message that should come back later, so one bad message no longer re-runs the others. Two batch-level calls exist as well: `batch.ackAll()`, which behaves like a successful return even if the handler later throws, and `batch.retryAll()`, which marks the whole batch for redelivery without throwing. A short checklist for reviewing a consumer that relies on the default: - Every message's work is awaited before `queue()` returns. - Nothing important is left as a floating promise; background work goes through `ctx.waitUntil()`. - A throw is acceptable only if redoing the whole batch is harmless. - Retries are bounded by `max_retries`, and a `dead_letter_queue` catches what exhausts them.
- Does work passed to ctx.waitUntil() inside a Queues consumer delay the batch's acknowledgement?Yes. The implicit acknowledgement waits for every promise passed to `ctx.waitUntil()`, and if one of them rejects the whole batch is treated as failed and retried. A promise that is neither awaited nor passed to `waitUntil()` does not hold the batch open and may not complete once the handler returns.
- What happens to a batch that throws on every delivery?Each failure redelivers every message in it until the messages have used up the consumer's `max_retries`, 3 by default. Then they are deleted, or written to the queue named in `dead_letter_queue` if one is configured. Each retry is also billed as an extra read operation.
- A Queues batch is acknowledged the moment it is delivered to the consumer.
- When queue() throws, only the message being processed at that moment is redelivered.
- batch.messages.forEach(async ...) finishes every send before the batch is acknowledged.
- Every message must call ack() or Queues redelivers it forever.
- A throwing Queues consumer simply drops the batch with no retry.