In Cloudflare Queues, what does the contentType option on send() change, and when does v8 matter instead of the default json?
answer
- four serialisation formats
- what JSON.stringify drops
- a Date that arrives as a string
- who else must read the body
basics
~20 scontentType picks how a Cloudflare Queues message body is serialised: json (the default for compatibility dates after 2024-03-18), text, bytes or v8. json loses values such as Date and Map; v8 keeps them but only Workers consumers can decode it.
solid answer
~40 sThe option takes one of four values. `json` serialises the body like `JSON.stringify`, which is the default for Workers with a compatibility date after 2024-03-18; `text` requires a string; `bytes` requires an `ArrayBuffer` view; `v8` uses the Workers runtime's structured-clone serialiser. With `json`, a `Date` reaches the consumer as an ISO string and a `Map` as an empty object, without any error. `v8` preserves them, but HTTP pull consumers cannot decode it and the dashboard cannot preview it. A body that does not match the declared type, such as an object sent as `text`, makes `send()` throw a `TypeError`. Every format still has to fit the 128 KB message limit after serialisation.
code
javascript · 14 linesexport default {
async fetch(request, env) {
const order = { orderId: "o-1", placedAt: new Date(), tags: new Map([["gift", true]]) };
await env.ORDERS.send(order);
await env.ORDERS.send(order, { contentType: "v8" });
return new Response("sent twice", { status: 202 });
},
async queue(batch) {
for (const m of batch.messages) {
console.log(m.body.placedAt instanceof Date, m.body.tags instanceof Map);
}
},
};go deeper
Recall the four values, json, text, bytes and v8, and that json is the default for new Workers.
Explain what json drops silently, Date to string and Map to empty object, and that v8 preserves types but only Workers can read it.
Choose the format from the set of consumers, including any planned pull consumer, and catch the TypeError a mismatched body throws on send().
Set a team rule that queue bodies are JSON-shaped and schema-versioned, so new consumers, pull consumers and dashboard previews all keep working.
## What the option is Every message a producer writes to **Cloudflare Queues** is serialised before it is stored. The optional `contentType` field chooses the serialiser. It can be passed to `send(body, { contentType })` or set per item in `sendBatch([{ body, contentType }])`; the batch-level options of `sendBatch()` only carry `delaySeconds`. | Value | Accepts | Consumer receives | Readable by | |---|---|---|---| | `json` | anything `JSON.stringify` accepts | the parsed JSON value | Worker and HTTP pull consumers, dashboard preview | | `text` | a string only | the same string | Worker and HTTP pull consumers, dashboard preview | | `bytes` | an `ArrayBuffer` view such as a `Uint8Array` | the bytes | Worker consumers; pull consumers decode them, dashboard shows Base64 | | `v8` | any structured-cloneable value | the same value, types preserved | Worker consumers only; dashboard shows Base64 | For Workers whose `compatibility_date` is **after 2024-03-18**, the default is `json`; before that it was `v8`. The `queues_json_messages` compatibility flag controls this, and `no_queues_json_messages` restores the old default. A Worker created today gets `json` without asking. ## What json silently drops `json` behaves like `JSON.stringify` followed by `JSON.parse`, so anything JSON cannot represent changes shape on the way through, **with no error on either side**: - A `Date` becomes its ISO-8601 string, so `message.body.placedAt.getTime()` throws in the consumer. - A `Map` or `Set` becomes `{}`, so the data is lost outright. - `undefined` properties disappear, `BigInt` values make serialisation throw, and class instances arrive as plain objects. In the order-ingestion example, a producer that sends `{ orderId, placedAt: new Date() }` gets a consumer that sees `placedAt` as a string. That is fine if the consumer expects a string, and a latent bug if it expects a `Date`. ## When v8 is the right choice `v8` uses the structured-clone algorithm, so `Date`, `Map`, `Set`, typed arrays and nested structures arrive with their types intact. Choose it when **both** of these hold: 1. Every consumer of the queue is a Worker. An **HTTP pull consumer cannot decode `v8`** because the format is specific to the Workers runtime; the pull-consumer docs warn to send only `text`, `bytes` or `json` to such a queue. 2. The team accepts that the dashboard's message list shows `v8` and `bytes` bodies as Base64 rather than a readable preview. The usual alternative is to keep `json` and make the body JSON-shaped on purpose: send `placedAt.toISOString()` or epoch milliseconds, and turn maps into plain objects or arrays of pairs. A JSON-shaped body also survives a later move to a pull consumer outside Workers. ## Types do not travel with the declaration In TypeScript, `Queue<Order>` on the producer and `ExportedHandler<Env, Order>` on the consumer type `message.body`, but the generic knows nothing about serialisation. A field declared as `placedAt: Date` type-checks on both sides and still arrives as a string under `json`. The compiler will not catch the mismatch; a test that sends a real message through the queue, or a body schema that uses strings and numbers only, will. ## Choosing a format in practice 1. Default to **`json`** for anything a person, the dashboard or another service may need to read, and keep the body JSON-shaped. 2. Use **`text`** when the payload is already a string, such as a log line or a pre-serialised document, and must arrive byte-for-byte as sent. 3. Use **`bytes`** for binary payloads such as a compressed blob, wrapped in a `Uint8Array`. 4. Reserve **`v8`** for Worker-to-Worker pipelines that genuinely need structured-clone types and will never gain a pull consumer. ## Mismatches and size limits The serialiser checks that the body matches the declared type. Sending an object with `{ contentType: "text" }` throws a `TypeError` whose message reads `Content Type "text" requires a value of type string, but received: object`; `bytes` fails the same way for anything that is not an `ArrayBuffer` view, a bare `ArrayBuffer` included, so wrap it in a `Uint8Array` first. Because the error surfaces on the producer, catch it where the request is handled and return an error to the caller instead of a false "accepted". The **128 KB** per-message limit applies to the stored message, about 100 bytes of internal metadata included, and `sendBatch()` is also capped at 256 KB per call. Different formats produce different sizes for the same value, so a body near the limit should be measured in the format actually sent.
- A team adds an HTTP pull consumer to a Cloudflare queue that producers fill with v8 messages. What breaks, and what is the fix?The pull consumer cannot decode `v8`, because that format is specific to the Workers runtime, so it receives bodies it cannot turn back into values. The fix is on the producers: switch them to `json`, `text` or `bytes`, and reshape bodies so they are JSON-representable, before the pull consumer goes live.
- What happens when a Cloudflare Queues producer calls send(42, { contentType: "text" })?`send()` throws a `TypeError` before anything is written, because the `text` serialiser requires a string and was given a number. Converting with `String(42)` or switching to `json` fixes it. The error appears in the producer, so it should be caught and reported to the caller rather than ignored.
- The default content type of Queues messages is v8 for new Workers.
- A Date sent with the json content type arrives as a Date object.
- Pull consumers outside Workers can decode v8 message bodies.
- sendBatch() options set a contentType for every message in the batch.
- An object sent with contentType text is stringified automatically.
Assumes a compatibility date after 2024-03-18, when the default Queues content type changed from v8 to json (flag queues_json_messages).