skip to content

In Cloudflare Queues, what does the contentType option on send() change, and when does v8 matter instead of the default json?

level: middleimportance: should knowfreq 22%

answer

  1. four serialisation formats
  2. what JSON.stringify drops
  3. a Date that arrives as a string
  4. who else must read the body

basics

~20 s

contentType 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 s

The 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 lines
javascript
export 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

for a junior

Recall the four values, json, text, bytes and v8, and that json is the default for new Workers.

for a middle

Explain what json drops silently, Date to string and Map to empty object, and that v8 preserves types but only Workers can read it.

for a senior

Choose the format from the set of consumers, including any planned pull consumer, and catch the TypeError a mismatched body throws on send().

for a principal

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).