# wrangler queues consumer failed: batch size too large

## TL;DR

The consumer's max_batch_size exceeds what the handler can process (time or memory), so batches fail. Lower max_batch_size, make the handler faster, or split work. The batch setting must fit the handler's real capacity.

```text
wrangler queues consumer failed: batch size too large
```

## Steps

1. Check the consumer's max_batch_size and the handler's actual per-message cost.
   Expected: The mismatch is quantified.

2. Lower max_batch_size to what the handler reliably processes within limits.
   Expected: Batches complete.

3. Speed up the handler if the batch size is business-required: less per-message work, more parallelism.
   Expected: Capacity rises.

4. Watch for poison messages: one bad message can fail the whole batch repeatedly.
   Expected: Dead-letter it.

5. Set max_retries and a dead-letter queue so failures are bounded.
   Expected: The queue stays healthy.

## When to use

- queue consumers fail on batch size
- handlers time out mid-batch
- batch settings were raised recently

## When not to use

- single messages fail (that is the handler, not the batch)
- the error is on produce, not consume (different path)
- the batch size is already small (look for poison messages)

## Tool compatibility

- wrangler
- Cloudflare Queues

## Variant phrasings

- "queues consumer batch size too large"
- "queue batch failed too large"
- "max_batch_size consumer failed"

## Why it happens

Batches multiply the handler's per-message cost by the batch size, and the product must fit in the worker's time and memory limits. Raising max_batch_size for throughput without measuring the handler turns the consumer into a batch-sized failure. The setting is a capacity contract.

## Edge cases

- the product of batch size and per-message time is what matters, not either alone
- poison messages fail whole batches; the dead-letter queue is essential
- batch timeouts interact with max_batch_timeout; tune both together

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xxCsKknAKwAcPbLfY3qZsg