Storage
Queues
Send and consume Cloudflare Queues messages with OpenOrange, backed by one Rivet Actor per queue.
Runs on Internal Rivet Actor per queue, delivered to the Worker's queue() handler
- Works
send(),sendBatch(), delays,ack(),retry(), retries, and dead-letter queues, with Cloudflare's consumer defaults- Differs
- Each queue delivers one batch at a time, so
max_concurrencyis ignored. Cloudflare's size, batch, and delay quotas do not apply. - Missing
oldestMessageTimestampin queue metrics, and thewrangler queuescommands- Migration
- Not supported
orange migratedoes not move messages waiting on a Cloudflare queue. Copy the data yourself.
- Configure
queues.producersqueues.consumers- Scales by
- Queue
- Checks
- 1 pass
A queue on OpenOrange is one Rivet Actor that keeps its messages in SQLite and
delivers them to your Worker’s queue() handler. Your Queues code and Wrangler
configuration run unchanged.
Quickstart
-
Bind the queue
Add a producer and a consumer to
wrangler.jsonc. Here one Worker both sends to the queue and consumes it.{ "name": "queues", "main": "src/index.ts", "compatibility_date": "2026-09-03", "queues": { "producers": [{ "binding": "JOBS", "queue": "jobs" }], "consumers": [{ "queue": "jobs", "max_batch_timeout": 1, "max_retries": 2 }] } } -
Send and consume messages
send()stores a message. Thequeue()handler gets it in a batch, andack()removes it from the queue.interface Job { id: string; } interface Env { JOBS: Queue<Job>; } export default { async fetch(request, env): Promise<Response> { const job = await request.json<Job>(); await env.JOBS.send(job); return Response.json({ queued: job.id }, { status: 202 }); }, async queue(batch, env): Promise<void> { for (const message of batch.messages) { console.log(`Ran job ${message.body.id} on attempt ${message.attempts}`); message.ack(); } }, } satisfies ExportedHandler<Env, Job>; -
Run it
orange devshows the queue as a Rivet Actor.orange dev Binding Resource Runs on env.JOBS Queue Rivet Actor · jobsSend a job. The
queue()handler then logs it in theorange devoutput.curl -X POST localhost:8787/jobs -d '{"id":"a"}' {"queued":"a"}Messages that wait in the queue survive a restart of
orange dev.
How it works
- Each queue is one Rivet Actor, named by the queue. It keeps each message in its SQLite database until the consumer acks it, so messages survive restarts.
- The actor delivers one batch at a time to
queue(), with Cloudflare’s rules forack(),retry(), retries, and dead-letter queues. - Every Worker of one
orange devsession that names a queue shares it. See Multiple Workers.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
| Feature | Status | Notes |
|---|---|---|
send() and sendBatch() | Supported | text, bytes, json, and v8 content types. json is the default. |
delaySeconds and the producer’s delivery_delay | Supported | Any whole number of seconds, 0 or more. No 24-hour maximum. |
queue() with ack(), retry(), ackAll(), and retryAll() | Supported | Cloudflare’s rules. See Delivery. |
retry({ delaySeconds }) and retryAll({ delaySeconds }) | Supported | |
max_batch_size, max_batch_timeout, max_retries, retry_delay | Supported | Cloudflare’s production defaults, with no maximums. See Consumer settings. |
dead_letter_queue | Supported | The dead-letter queue is a normal queue, so a Worker can consume it. |
max_concurrency | Not supported | Ignored. Each queue runs one batch at a time. |
metrics(), the metadata that send() returns, and batch.metadata | Partial | Count the messages that are due. oldestMessageTimestamp is never set. |
wrangler queues commands | Not supported | orange queues prints that the command is not implemented. |
Two differences reach most projects:
- The consumer defaults are Cloudflare’s production ones, not the smaller
ones of
wrangler dev. Set the values inwrangler.jsoncto get the same batches in both. - Messages wait when no Worker of the session consumes the queue, like a
Cloudflare queue with no consumer.
wrangler devdrops them.
Limits
Orange does not copy Cloudflare’s quotas: 128 KB per message, 100 messages
and 256 KB per sendBatch(), 100 messages per batch, a 60-second batch
timeout, 100 retries, and 24-hour delays. Rivet’s limits apply:
| What | Limit | What happens over it |
|---|---|---|
One send() or sendBatch() | 32 MiB of message bodies, because the call is one message to the Rivet Engine. A 31 MiB message was measured to work. | The call throws a RangeError at once that names the limit, and stores nothing. Split the batch. |
| Batches on one queue | One at a time, through one Rivet Actor | Carry more messages per call with sendBatch(), or spread the load over more queues. |
The full error is
RangeError: Queue send failed: the messages are <n> bytes. One send() or sendBatch() is one message to Rivet's Engine, which takes at most 33554432 bytes (32 MiB). Split the batch.
Consumer settings
| Setting | Default | Range |
|---|---|---|
max_batch_size | 10 | 1 or more |
max_batch_timeout | 5 seconds | 0 or more, fractions allowed |
max_retries | 3 | 0 or more |
retry_delay | 0 seconds | 0 or more |
wrangler dev uses 5 messages, 1 second, and 2 retries. Each of these errors
stops orange dev:
Queue consumer <queue>.<setting> must be an integer of <minimum> or more, ora number of 0 or moreformax_batch_timeout.Queue producer <binding>.delivery_delay must be an integer of 0 or more.Queue <queue> has more than one consumer, for two consumers of one queue in one Worker. Across Workers, see Multiple Workers.
Sending
- A body of
undefined, a body that does not match its content type, and an unknown content type throw aTypeError, as in workerd:Message body cannot be undefined,Content Type "text" requires a value of type string, but received: number, andUnsupported queue message content type: xml. - An empty
sendBatch()throwssendBatch() requires at least one message. - A delay that is not a whole number of seconds, 0 or more, throws
Queue send failed: message delay -1 is invalid. It must be a whole number of seconds, 0 or more. - In
sendBatch(), a message’sdelaySecondswins over the batch’s, which wins over the producer’sdelivery_delay. - A delayed message is stored with the time it becomes available. A Rivet schedule wakes the actor at the earliest pending time.
- A
sendBatch()is stored in one transaction, so a rejected message stores none of the batch. - Message IDs are 32 hexadecimal characters, as on Cloudflare.
Delivery
- A batch holds up to
max_batch_sizedue messages. With fewer due, the actor waits up tomax_batch_timeoutfrom the first due message, so after an idle period the first batch waits the whole timeout. ack(),retry(),ackAll(), andretryAll()follow Cloudflare’s rules: the first call wins, and a later conflicting call logs a warning. A call on one message wins over a batch call. An explicitack()holds even when the handler throws. A message with no call is acked when the batch succeeds.- A retry waits the message’s
retry({ delaySeconds }), then the batch’sretryAll({ delaySeconds }), then the consumer’sretry_delay. - A batch completes only after
queue()and itswaitUntil()promises settle. If the handler throws, or awaitUntil()promise rejects, every message that was not acked is retried. The errors appear in theorange devoutput. - If
orange devstops or crashes duringqueue(), the batch is delivered again after the restart. Delivery is at least once. - A message gets
max_retries + 1deliveries. Then it goes to thedead_letter_queuewith its ID, timestamp, and body, and itsattemptscount starts again at 1. Without a dead-letter queue, it is dropped withDropped message "<id>" on queue "<queue>" after <n> failed attempts!. - A consumer Worker without a
queue()handler fails each batch withHandler does not export a queue() function. - A message row is deleted only after the consumer acks it, sends it to the dead-letter queue, or drops it. The actor sends dead letters before it deletes their rows, so a crash redelivers instead of losing a message.
Storage
- The actor class is
openorange:queue, shown asQueues (Orange), and its key is the queue name. - Messages are rows of one table,
messages, in the actor’s SQLite database. Underorange dev, it lives in the project’s.open-orangedirectory. - A consumer in another Worker of the session receives the batches of a queue that this Worker produces to.
Registry message size
Orange raises the RivetKit registry option maxIncomingMessageSize from its
64 KiB default to 32 MiB, the most the Rivet Engine takes in one message from
a runner. RivetKit checks this limit on each action request, each queue send
over HTTP, and each message on an actor-connect WebSocket. send() and
sendBatch() reach the queue actor as one action request.
The option applies to every actor in the registry, including Durable Objects,
facets, and the Workflows and cron actors. Durable Object and facet fetch(),
RPC, and WebSocket traffic do not use RivetKit actions, so the limit does not
change them.
Deviations
These add to the differences under Compatibility.
- A batch that is delivered again after a crash keeps its
attemptsvalue. - One actor is the single writer for a queue, so every
send(),sendBatch(), and batch delivery on it goes through that actor. Sharding a queue across actors, or backing Queues with a Rivet Service, may lift this bound later.
Conformance
tests/bindings/queues.test.tsdrives Queues through a realorange dev: retries up tomax_retriesand the dead-letter queue,retry({ delaySeconds }), batches from concurrent producers, a 128,000-byte message and one over Cloudflare’s 128 KB, send validation errors, a crash duringqueue(), and a delayed message across a restart.tests/bindings/beyond-cloudflare-quotas.test.tssends a 1 MiB message, a 3-day delay, and a batch of 250, and a send over 32 MiB that fails with Rivet’s limit.tests/examples/runnable-examples.test.tsruns thequeuesexample: retries with backoff, the dead-letter queue, message and batch delays, each content type,retryAll(), andmetrics().tests/bindings/multi-worker.test.tssends to a queue from one Worker and consumes it in another, and checks that two consumers of one queue fail at startup.- The
scale-unitsprobe checks that each queue is one actor. - workerd’s upstream
queue-testandqueue-metadata-testfail. They use a mock queue service that the conformance runner does not configure, so their queue binding is dropped.
Recorded results
Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.
Queues
| Check | Status | Results |
|---|---|---|
| Queues | Works |
|