skip to content

In Cloudflare Workers, what does a Worker's compatibility_date pin, and how do compatibility_flags adjust what that date turns on?

level: middleimportance: should knowfreq 42%

answer

  1. runtime changes gated by date
  2. on or before the date
  3. next deploy, never automatic
  4. enable flag versus disable flag

basics

~20 s

A compatibility_date gives a Worker every gated runtime change dated on or before it, so its behaviour holds until the team changes the date and redeploys. compatibility_flags enable one change early or keep one off.

solid answer

~40 s

Cloudflare gates each backwards-incompatible runtime change behind a flag with an enable date. A Worker's `compatibility_date` turns on every change dated on or before it, and the runtime supports old dates indefinitely, so a Worker keeps its behaviour while the platform moves on. A new date takes effect only at the next deploy; redeploying never moves it. `compatibility_flags` adjust single changes: an enable flag such as `nodejs_compat` turns one on before its date, and a disable flag such as `retain_authorization_on_cross_origin_redirect` keeps one off after it. The runtime rejects an unknown flag name and an enable flag listed with its own disable flag.

code

json · 6 lines
json
{
  "name": "pricing-api",
  "main": "src/index.js",
  "compatibility_date": "2026-10-01",
  "compatibility_flags": ["retain_authorization_on_cross_origin_redirect"]
}

go deeper

for a junior

Recall that compatibility_date is set in the Wrangler file, usually to the day the project starts, and that it fixes which runtime behaviour the Worker gets.

for a middle

Explain the on-or-before rule, that the date only changes on a redeploy with a new value, and how enable and disable flags adjust single changes.

for a senior

Show you read the flags history between two dates before a bump, and use a disable flag to hold back one change while the code is fixed.

for a principal

Treat the date as a versioned dependency: who may move it, how often, and how held-back flags are tracked until they are removed.

## What a compatibility date is Cloudflare updates the **Workers runtime** (workerd) continuously, and the update reaches every Worker on the platform at once. Most changes are additions and fixes nothing could depend on. Some are not: a bug fix that makes an API follow the Fetch specification can break a Worker that leaned on the old, wrong behaviour. Cloudflare's answer is to gate each such change behind a **compatibility flag** with an **enable date**, and to let each Worker declare a `compatibility_date`. The rule is simple: a Worker gets **every gated change whose enable date is on or before its `compatibility_date`**, and none dated after it. A Worker dated `2024-10-01` keeps 2024-10-01 behaviour while the runtime moves on; the runtime promises to support old dates indefinitely, and Cloudflare says it will contact affected developers in the rare case it must break a live Worker anyway. ## When a new date takes effect - The date is part of the Worker's configuration, so a new value takes effect at the **next deploy** (`wrangler deploy`, a version upload, the dashboard or the API). - Deploying does **not** move the date. A Worker deployed every day for two years with an unchanged `compatibility_date` still runs two-year-old semantics. - A Worker uploaded through the API with no date gets the oldest date, `2021-11-02`, before any flag took effect. - Wrangler refuses a date later than today: `Compatibility date "2026-10-12" is in the future and unsupported`. The local runtime also has a ceiling, the newest date its build supports. - `wrangler deploy --latest` uses the newest date the installed Wrangler supports, and `--compatibility-date` overrides the file for one command. ## Flags: one change at a time `compatibility_flags` is a list of flag names that adjusts the result of the date for **individual changes**: 1. **An enable flag** turns a change on before its date arrives, or turns on a change that has no default date yet. 2. **A disable flag** keeps a change off even though the date has passed its enable date, so a team can take every other change while one piece of code is fixed. Each gated change has its own pair of names, and they do not follow one pattern: | Change | Enable flag | Default from | Disable flag | |---|---|---|---| | Node.js compatibility | `nodejs_compat` | 2026-08-04 | `no_nodejs_compat` | | Upper-case every HTTP method | `upper_case_all_http_methods` | 2024-10-14 | `no_upper_case_all_http_methods` | | Drop `Authorization` on a cross-origin redirect | `strip_authorization_on_cross_origin_redirect` | 2025-09-01 | `retain_authorization_on_cross_origin_redirect` | | Node.js-style timer objects | `enable_nodejs_global_timers` | 2026-02-10, with Node.js compatibility on | `no_nodejs_global_timers` | Some changes are **implied** by another flag after a date rather than having a date of their own: the Node.js `fs`, HTTP client and timer behaviours, for example, switch on only when Node.js compatibility is on and the date has passed theirs. ## What the runtime checks The runtime validates the list when it loads the Worker: - an unknown name stops it: `No such compatibility flag: nodejs_compatibility`; - an enable flag and its own disable flag together stop it: `Compatibility flags are mutually contradictory: nodejs_compat vs no_nodejs_compat`; - the same name twice is an error: `Compatibility flag specified multiple times`; - an enable flag the date already turns on is redundant: the runtime logs a warning such as `The compatibility flag formdata_parser_supports_files became the default as of 2021-11-03 so does not need to be specified anymore.` and carries on. A disable flag for a change whose date has not yet arrived is accepted silently, so a team can add it ahead of a bump. ## A worked example Take a Worker dated `2024-10-01` with `compatibility_flags: []`. Moving it to `2025-10-01` turns on, among others, `upper_case_all_http_methods` (2024-10-14) and `strip_authorization_on_cross_origin_redirect` (2025-09-01). Node.js compatibility stays off, because its default date is 2026-08-04 and the list does not name `nodejs_compat`. If one service the Worker calls depends on the `Authorization` header surviving a redirect to another host, the team can bump anyway and add `retain_authorization_on_cross_origin_redirect`, taking every other change while that one call is fixed. Moving the date again to `2026-10-01` would also turn Node.js compatibility on, with everything that rides on it, which is why each bump is read against the flags history rather than assumed to be harmless. ## Reading a Worker's behaviour To know how a Worker behaves you need both values: the date selects a baseline, and the flags adjust single entries. Cloudflare's documentation generally describes the current date's behaviour; the **compatibility flags history** page lists each change with its flag names and date, and is where a team reads what a bump from one date to another will change.

  • What compatibility date does a Worker get when it is uploaded through the Cloudflare API without one?
    The oldest date, `2021-11-02`, before any compatibility flag took effect. The Worker therefore runs the runtime's oldest semantics, which is why the API documentation recommends always sending the current date. Wrangler will not deploy without one: it offers its default date or stops with `A compatibility_date is required when publishing`, while `wrangler dev` warns and falls back to its default date.
  • What happens if `compatibility_flags` names a change the date already turns on?
    Nothing changes in behaviour: the compiled flag set is the same. The runtime logs a warning that the flag became the default as of its date and need not be listed. Wrangler goes further for `nodejs_compat` and `nodejs_compat_v2` on dates from 2026-08-04, dropping them before starting the runtime, so old configurations keep working after a bump.
  • Can a team set the compatibility date a few days ahead to pick up an announced change early?
    No. Wrangler rejects a date after today with `Compatibility date "..." is in the future and unsupported`, and the runtime itself refuses future dates. To get one upcoming change early, list its enable flag in `compatibility_flags` while keeping a current date.

A building permit is judged against the building-code edition in force when it was filed. Later editions do not apply to it until the owner files again, and a variance can waive one clause of the newer edition.

  • Cloudflare moves every deployed Worker onto new runtime behaviour automatically.
  • The compatibility date is simply the date the Worker was last deployed.
  • Old compatibility dates are retired, so every Worker must bump yearly.
  • Every disable flag is the enable flag's name with no_ in front.
  • Listing a flag and its disable flag lets the later one win.