Cloudflare Workers compatibility_date: Safe Upgrade

What compatibility_date controls#

In a Wrangler configuration file, the setting looks like this:

1
name = "example-worker"
2
main = "src/index.ts"
3
compatibility_date = "2026-01-15"

The date is a bundle of runtime behavior choices. Compatibility flags often become enabled by default on a particular date, and setting a later date opts into those changes. The Cloudflare compatibility-date documentation says the new date takes effect on the next wrangler deploy.

That means a committed configuration change alone does not change the already deployed Worker. Conversely, changing the date and deploying can change runtime behavior even when the Worker source code is unchanged.

Account for the 2026-08-04 Node.js compatibility boundary#

Cloudflare changed the default for Node.js compatibility at 2026-08-04. Workers with a compatibility date on or after that date enable nodejs_compat and nodejs_compat_v2 by default, so a new configuration does not need to list those positive flags. Existing configurations may keep them while upgrading; the flags are redundant for the newer date rather than a reason to avoid the date change.

For an older compatibility date, the opt-in remains explicit:

1
{
2
  "compatibility_date": "2026-08-03",
3
  "compatibility_flags": ["nodejs_compat"]
4
}

If the Worker must turn Node.js compatibility off after moving to 2026-08-04 or later, remove the positive flags and add both no_nodejs_compat and no_nodejs_compat_v2. Do not infer that a Node.js module is fully compatible merely because it imports: Cloudflare documents a supported subset, partial implementations, and polyfills whose methods can still throw at runtime. Test the package path that the Worker actually executes.

This boundary is a concrete example of why compatibility_date deserves a staged review. A date update can change whether an npm dependency resolves, whether Wrangler injects a shim, or whether an API is provided by the runtime itself.

Review the flags before moving the date#

Open the compatibility flags reference and compare the current date with the date you plan to use. Look for flags that affect APIs your Worker actually uses: request parsing, streams, Web APIs, Node.js compatibility, module behavior, or other runtime boundaries.

A specific exception can be expressed with compatibility_flags:

1
compatibility_date = "2026-01-15"
2
compatibility_flags = ["example_flag"]

Use a real flag from the Cloudflare reference, not the placeholder above. Flags can enable a change before its default date or hold back a change that became default. Document why the exception exists and create a follow-up task; an unexplained compatibility flag becomes another piece of runtime archaeology.

Use a staged upgrade sequence#

Make the upgrade observable and reversible:

1. Record the currently deployed date and any compatibility flags.
2. Read the flag entries between the old and target dates.
3. Run unit and integration tests with the target configuration.
4. Exercise the Worker locally with wrangler dev or the project’s test harness.
5. Deploy to a non-production Worker or a controlled traffic path when available.
6. Run smoke tests for authentication, bindings, request parsing, storage, and error responses.
7. Deploy production, then monitor logs and application-level metrics.

The local Workers test harness guide is useful when the change needs request-level coverage. Include the compatibility date in the test fixture so a future test run does not silently use a different runtime contract.

A dry-run build can catch configuration and bundling mistakes, but it cannot prove that every runtime behavior is unchanged. Keep at least one test for each API boundary the Worker depends on.

Roll back by configuration when necessary#

If the new date exposes a regression, revert the configuration to the last known-good date and deploy that commit. Cloudflare’s documentation says old compatibility dates continue to be supported, so the date is a practical rollback boundary when the source code is otherwise unchanged.

Do not remove a flag during an incident unless you know whether it enables or disables the behavior you need. A flag override can make the configuration appear to work while leaving the next date upgrade unpredictable. Prefer a small, reviewed change with a comment or issue that explains the temporary exception.

Avoid the API upload default#

Wrangler configuration is the clearest place to set the date. If a deployment system uploads a Worker through the Cloudflare API, set compatibility_date explicitly in the request metadata. The official documentation notes that an API upload without a date defaults to the oldest compatibility date, before compatibility flags took effect.

This is easy to miss in a custom deployment script because the dashboard and Wrangler may have a date while the API payload does not. Log the selected date, not secrets or full request metadata, as part of the deployment record.

FAQ#