queues

Cloudflare Queues

Build reliable asynchronous message processing on Cloudflare Workers using Queues for background tasks, batch operations, and retry handling.

When to Use

• Background Tasks - Offload non-critical work from request handlers
• Batch Processing - Accumulate messages and process in batches to reduce upstream API calls
• Retry Handling - Automatic retries with configurable delays for transient failures
• Decoupling - Separate producers from consumers for scalability
• Rate Limiting Upstream - Control the rate of requests to external APIs
• Dead Letter Queues - Capture and inspect failed messages for debugging

Quick Reference

Task	API
Send single message	env.QUEUE_BINDING.send(payload)
Send batch	env.QUEUE_BINDING.sendBatch([msg1, msg2])
Define consumer	async queue(batch: MessageBatch, env: Env) { ... }
Access message body	batch.messages.map(msg => msg.body)
Acknowledge message	Messages auto-ack unless handler throws
Retry message	throw new Error() in queue handler
Get batch size	batch.messages.length

FIRST: wrangler.jsonc Configuration

Queues require both producer and consumer configuration:

{
  "name": "request-logger-consumer",
  "main": "src/index.ts",
  "compatibility_date": "2025-02-11",
  "queues": {
    "producers": [{
      "name": "request-queue",
      "binding": "REQUEST_QUEUE"
    }],
    "consumers": [{
      "name": "request-queue",
      "dead_letter_queue": "request-queue-dlq",
      "retry_delay": 300,
      "max_batch_size": 100,
      "max_batch_timeout": 30,
      "max_retries": 3
    }]
  },
  "vars": {
    "UPSTREAM_API_URL": "https://api.example.com/batch-logs",
    "UPSTREAM_API_KEY": ""
  }
}

Consumer Options:

• dead_letter_queue - Queue name for failed messages (optional)
• retry_delay - Seconds to wait before retry (default: 0)
• max_batch_size - Max messages per batch (default: 10, max: 100)
• max_batch_timeout - Max seconds to wait for batch (default: 5, max: 30)
• max_retries - Max retry attempts (default: 3)