skip to content

A team set delivery_delay on a Cloudflare Queues producer binding to hold order events for 60 seconds, but production consumers get them at once. Why, and how should they delay messages?

level: seniorimportance: nice to knowfreq 15%

answer

  1. a warning Wrangler prints
  2. queue-level settings live elsewhere
  3. a per-message option overrides
  4. zero means no delay

basics

~20 s

Wrangler 4 warns that delivery_delay on queues.producers is deprecated and has no effect. Set a queue-level default with wrangler queues update orders --delivery-delay-secs=60, or pass delaySeconds to send() or sendBatch(); per-message values override the queue default.

solid answer

~40 s

The `delivery_delay` key in `queues.producers` has silently done nothing in production since 2024, and Wrangler now prints a warning that it is deprecated, has no effect and will be removed; queue-level settings belong to `wrangler queues update`. A local `wrangler dev` run can still apply the key, so a local test may look correct. There are two working delays. A queue-wide default is set on the queue itself with `wrangler queues update orders --delivery-delay-secs=60` (or at `wrangler queues create`), from 0 to 86,400 seconds. A per-message or per-batch delay is `send(body, { delaySeconds: 60 })` or `sendBatch(messages, { delaySeconds: 60 })`, up to 24 hours. A per-message value wins over the queue default, and `delaySeconds: 0` sends a message on the next batch even when the queue has a default delay.

code

bash · 1 line
bash
npx wrangler queues update orders --delivery-delay-secs=60

go deeper

for a junior

Know the per-message delaySeconds option on send() and sendBatch(), and its 24-hour maximum.

for a middle

Explain that the queue-wide default lives on the queue, set with wrangler queues update --delivery-delay-secs, and how per-message values override it.

for a senior

Read Wrangler's deprecation warning as the root cause, distrust a local run that shows the delay, and verify the fix in queue metrics.

for a principal

Decide whether delay policy lives in code as delaySeconds or in account state on the queue, and how the latter is recorded and reviewed.

## The symptom In the order-ingestion example, the fulfilment team wants each order event held for a minute so that quick cancellations arrive before fulfilment starts. Someone adds `"delivery_delay": 60` to the producer's binding in `queues.producers`, deploys, and finds that consumers still receive orders within seconds. Local tests looked fine. ## Why the key does nothing The **Cloudflare Queues** delay is a setting of the **queue**, not of a producer's binding. The `delivery_delay` field on a producer binding has had **no effect in production since 2024**. Wrangler's changelog records adding a warning for it in 4.90.0, and Wrangler 4 prints, while processing the configuration: > The "delivery_delay" field in "queues.producers[0]" is deprecated and has no effect. Queue-level settings should be configured using "wrangler queues update" instead. This setting will be removed in a future version. Two things make the mistake easy to keep: - Some documentation pages still describe the key as a default delay, so it looks supported. - The local simulator behind `wrangler dev` can still honour the key, so a local test shows the delay while production ignores it. The warning in the Wrangler output is the reliable signal. ## Where the delay belongs A queue can have any number of producer Workers. A default delay attached to one producer's binding would make the same queue hold some messages and not others depending on which Worker wrote them, which is hard to reason about. The working design keeps two levels apart: - a **queue-level default**, stored with the queue and applied to every message written to it, whoever wrote it; - a **per-message or per-batch override**, chosen in code at the moment of sending. The delay is also independent of the consumer: it does not change `max_batch_size`, `max_batch_timeout` or how many consumer invocations run. ## The two delays that work | Where | How | Range | Scope | |---|---|---|---| | Queue default | `wrangler queues create orders --delivery-delay-secs=60` or `wrangler queues update orders --delivery-delay-secs=60` | 0 to 86,400 seconds | every message written to the queue | | Per message | `env.ORDERS.send(body, { delaySeconds: 60 })` | 0 to 86,400 seconds (24 hours) | that one message | | Per batch | `env.ORDERS.sendBatch(messages, { delaySeconds: 60 })`, or `delaySeconds` on an item | up to 24 hours | the messages in that call | The queue-level value can also be set through the Queues REST API. Because it is account state rather than Worker code, it is not reviewed with the Worker's code changes, and a team should record where it is set. ## Precedence 1. A `delaySeconds` on the message or batch **takes precedence** over the queue default. 2. `delaySeconds: 0` explicitly **ignores** the queue default and lets the message ship in the next batch. 3. A positive `delaySeconds` longer or shorter than the queue default is respected as given. So one queue can hold ordinary orders for 60 seconds while an urgent order, sent with `delaySeconds: 0`, goes straight through. The same rules apply to `sendBatch()`: a `delaySeconds` in the call's options applies to every message in that call, and the queue default applies only to messages sent with no delay of their own. ## How the delay combines with batching A delay decides when a message becomes **eligible** for delivery. After that, the consumer's batching rules still apply: the message waits until its batch reaches `max_batch_size` or `max_batch_timeout` expires. With a 60-second delay and a 5-second batch timeout, a lone order can reach the consumer up to about 65 seconds after it was sent. Retry delays (`retry_delay`, and `delaySeconds` on `message.retry()`) are a separate mechanism, covered with Queues failure handling. ## Checking the fix - Remove `delivery_delay` from `queues.producers`, so the warning disappears and nobody relies on it again. - Run `wrangler queues update orders --delivery-delay-secs=60` against the right account, or add `delaySeconds` to the producer's `send()` calls. - Check the queue's message-operations metrics: `lagTime`, the average time between a message's write and its consumption, should rise to roughly the delay plus the batch wait. - Repeat the queue-level command for every queue the Worker's environments use, since a staging queue and a production queue are separate queues with separate settings.

  • What is the longest a Cloudflare Queues message can be delayed, and what happens past it?
    24 hours: `delaySeconds` and `--delivery-delay-secs` both accept up to 86,400 seconds, and a larger value is rejected rather than capped. Work that must wait longer, such as a 14-day trial reminder, belongs in a mechanism designed for long waits, such as a Workflow sleep or a Durable Object alarm, not a queue delay.
  • Why might a team prefer delaySeconds in producer code over a queue-level delay set with wrangler queues update?
    A `delaySeconds` value lives in the Worker's code, so it is reviewed, versioned and deployed with the change that needs it, and it is identical in every environment. A queue-level delay is account state set by a command, invisible in code review and easy to set on production but forget on staging. The queue default suits a delay every producer must honour.

  • delivery_delay on a producer binding sets the queue's default delay.
  • A clean local wrangler dev run proves the delay works in production.
  • The queue default always overrides a message's own delaySeconds.
  • delaySeconds: 0 means use the queue's default delay.
  • A message can be delayed for up to seven days.

Assumes Wrangler 4.90.0 or later, which warns that delivery_delay on a producer binding is deprecated and has no effect; queue-level delays are set with wrangler queues update.