skip to content

In Cloudflare Queues, what do max_batch_size and max_batch_timeout default to, and what does raising them save when Queues bills per message?

level: middleimportance: must knowfreq 42%

answer

  1. whichever limit is hit first
  2. ten and five by default
  3. operations counted per message
  4. fewer invocations, fewer downstream writes

basics

~20 s

max_batch_size defaults to 10 messages (up to 100) and max_batch_timeout to 5 seconds (up to 60); a batch ships when either is reached. Queues bills per message, so bigger batches save consumer invocations and downstream writes, at a latency cost.

solid answer

~50 s

Both keys sit on the `queues.consumers` entry and work together: Queues delivers a batch as soon as it holds `max_batch_size` messages or `max_batch_timeout` seconds have passed, whichever comes first. The defaults are 10 messages and 5 seconds; the ranges are 1 to 100 messages and 0 to 60 seconds. Queues bills an operation per message for each write, read and delete, so batch size does not change the Queues line of the bill. What larger batches cut is the number of consumer invocations and the number of writes to whatever sits downstream, for example one 100-row bulk insert instead of ten 10-row ones. The cost is latency: at low traffic a message can wait up to the full timeout before its batch ships. A larger batch also means more work redone if the handler throws, and the whole batch must finish inside one invocation's limits.

code

json · 13 lines
json
{
  "name": "fulfilment",
  "main": "src/index.js",
  "compatibility_date": "2026-10-10",
  "queues": {
    "consumers": [
      { "queue": "orders", "max_batch_size": 100, "max_batch_timeout": 10 }
    ]
  },
  "d1_databases": [
    { "binding": "DB", "database_name": "fulfilment", "database_id": "00000000-0000-0000-0000-000000000000" }
  ]
}

go deeper

for a junior

Know both key names, their defaults of 10 messages and 5 seconds, and that a batch ships when either limit is hit first.

for a middle

Explain the maximums of 100 messages and 60 seconds, and why per-message billing means batching saves invocations and downstream writes rather than queue operations.

for a senior

Size the batch from the downstream bulk write and the latency budget, and account for the whole batch replaying when the handler throws.

for a principal

Set team defaults per workload class, latency-sensitive versus bulk, and decide whether the Wrangler file or the CLI is the single place of record for consumer settings.

## What the two settings control A **push-based consumer** is a Worker whose `queue(batch, env, ctx)` handler Cloudflare invokes whenever messages are waiting. Two keys on its `queues.consumers` entry decide how many messages each invocation receives: - `max_batch_size` is the **most messages** one batch may hold. - `max_batch_timeout` is the **longest time, in seconds**, Queues waits to fill a batch before delivering whatever it has. They act together and **whichever limit is reached first** triggers delivery. With `max_batch_size: 30` and `max_batch_timeout: 10`, a burst of 30 messages ships immediately as one batch, while a trickle ships every 10 seconds with however many messages arrived (somewhere from 1 to 29). When the queue is empty, a push consumer is not invoked at all. | Setting | Default | Minimum | Maximum | |---|---|---|---| | `max_batch_size` | 10 messages | 1 message | 100 messages | | `max_batch_timeout` | 5 seconds | 0 seconds | 60 seconds | The same values can be set from the CLI with `wrangler queues consumer add <queue> <script> --batch-size 100 --batch-timeout 30`. If both the CLI and the Wrangler file change a consumer's settings, the most recent change wins, so a team should pick one place of record. ## Where the money actually goes Queues pricing counts **operations**: one for each 64 KB written, read or deleted, so a normal message costs about three (write, read, delete). The pricing page is explicit that operations are **per message, not per batch**: a batch of 10 messages incurs 10 reads, not one. Raising `max_batch_size` therefore does **not** shrink the Queues line of the bill. What it shrinks is everything around it: 1. **Consumer invocations.** A thousand messages in batches of 100 is ten invocations of the consumer Worker instead of a hundred at the default size. The Queues docs list fewer consumer invocations as a direct way to reduce cost. 2. **Downstream writes.** The fulfilment Worker in the order-ingestion example turns each batch into one bulk insert. Ten rows per statement against a database that charges, rate-limits or locks per write is far more expensive than 100 rows per statement. 3. **Load smoothing.** User-driven spikes on the producer side become a steadier stream of larger writes on the consumer side. ## What larger batches cost - **Latency at low traffic.** With a 60-second timeout and only a few orders a minute, an order can sit for up to a minute before its batch ships. A large `max_batch_size` with a short `max_batch_timeout` gives big batches under load and prompt delivery when quiet. - **Bigger blast radius.** If the handler throws, the whole batch is retried unless messages were acknowledged individually, so one bad message in a 100-message batch replays 99 good ones. Acknowledgement and retry are covered with Queues failure handling. - **One invocation's budget.** The whole batch must finish within one consumer invocation: 15 minutes of wall time, and a CPU-time limit (30 seconds by default on the paid plan) that `limits.cpu_ms` can raise. - **Downstream limits.** The batch should not exceed what one bulk write can accept, such as a statement or payload size limit in the target database. ## A worked example Take the fulfilment consumer configured with `max_batch_size: 100` and `max_batch_timeout: 10`: - **Busy hours, 1,000 orders a minute.** About 17 orders arrive each second, so a batch fills to 100 in roughly 6 seconds and ships on size. That is about 10 invocations and 10 bulk inserts a minute, where the defaults would have produced about 100 of each. - **Quiet hours, 20 orders a minute.** One order arrives every 3 seconds, so batches ship on the timeout with 3 or 4 orders each: about 6 invocations a minute, and no order waits more than about 10 seconds for its batch. - **Bill.** In both cases the Queues operations are the same per order, about three each; only the invocation and insert counts move. ## A working method 1. Start from the downstream write: how many rows can one bulk insert take safely? That caps `max_batch_size`. 2. Ask how long a message may wait when traffic is low; that is the ceiling for `max_batch_timeout`. 3. Watch the backlog in the queue's metrics. A backlog that keeps growing usually means each batch takes too long to process; a bigger batch helps only when per-invocation overhead, not per-message work, is the bottleneck. ## A local-development trap When the keys are left unset, the local simulator behind `wrangler dev` uses its own defaults (batches of 5 after 1 second), not production's 10 and 5 seconds. Setting both keys explicitly keeps local runs and production delivering batches the same way.

  • Why might a Cloudflare Queues consumer set max_batch_timeout to 0?
    A timeout of 0 tells Queues not to wait to fill a batch, so messages are delivered as soon as they are available, in whatever count is waiting up to `max_batch_size`. It suits latency-sensitive work such as password-reset emails, where waiting several seconds to save invocations is the wrong trade.
  • Does a pull-based Cloudflare Queues consumer use max_batch_size?
    No. `max_batch_size` and `max_batch_timeout` shape what Queues pushes to a Worker's `queue()` handler. An HTTP pull consumer chooses its batch per request with `batch_size` in the pull call's JSON body (default 5, maximum 100), and there is no batch timeout: a pull returns at once with what is available, or with nothing.
  • A Cloudflare Queues consumer's backlog keeps growing even at max_batch_size 100. What does that tell you?
    The batch ceiling is already at its limit, so the consumer is too slow per batch. The fix is downstream: a faster bulk write, less per-message work, or more concurrent consumer invocations, which Queues scales automatically and which the failure-handling material covers with max_concurrency.

  • Raising max_batch_size cuts the Queues operations bill proportionally.
  • Queues waits for max_batch_size messages even after max_batch_timeout passes.
  • max_batch_timeout is measured in milliseconds.
  • max_batch_size can go to 1,000 for high-volume queues.
  • An empty queue still invokes the consumer every max_batch_timeout.