Compatibility flags·续7

The following stubs are enabled automatically only when nodejs_compat is enabled and your Worker's compatibility date is on or after the date shown:

Stub module Enabled with nodejs_compat on or after Enable flag Disable flag
node:http2 ↗︎ 2025-09-01 enable_nodejs_http2_module disable_nodejs_http2_module
node:vm ↗︎ 2025-10-01 enable_nodejs_vm_module disable_nodejs_vm_module
node:cluster ↗︎ 2025-12-04 enable_nodejs_cluster_module disable_nodejs_cluster_module
node:domain ↗︎ 2025-12-04 enable_nodejs_domain_module disable_nodejs_domain_module
node:trace_events ↗︎ 2025-12-04 enable_nodejs_trace_events_module disable_nodejs_trace_events_module
node:wasi ↗︎ 2025-12-04 enable_nodejs_wasi_module disable_nodejs_wasi_module
node:_stream_wrap 2026-01-29 enable_nodejs_stream_wrap_module disable_nodejs_stream_wrap_module
node:dgram ↗︎ 2026-01-29 enable_nodejs_dgram_module disable_nodejs_dgram_module
node:inspector ↗︎ 2026-01-29 enable_nodejs_inspector_module disable_nodejs_inspector_module
node:sqlite ↗︎ 2026-01-29 enable_nodejs_sqlite_module disable_nodejs_sqlite_module
node:child_process ↗︎ 2026-03-17 enable_nodejs_child_process_module disable_nodejs_child_process_module
node:readline ↗︎ 2026-03-17 enable_nodejs_readline_module disable_nodejs_readline_module
node:repl ↗︎ 2026-03-17 enable_nodejs_repl_module disable_nodejs_repl_module
node:tty ↗︎ 2026-03-17 enable_nodejs_tty_module disable_nodejs_tty_module
node:v8 ↗︎ 2026-03-17 enable_nodejs_v8_module disable_nodejs_v8_module
node:worker_threads ↗︎ 2026-03-17 enable_nodejs_worker_threads_module disable_nodejs_worker_threads_module

When enabling nodejs_compat, we recommend using the latest version of Wrangler CLI, and the latest compatibility date, in order to maximize compatibility. Some older versions of Wrangler inject additional polyfills that are no longer necessary when your Worker uses a more recent compatibility date, because they are provided by the Workers runtime.

For compatibility dates of 2026-08-04 or later, nodejs_compat and nodejs_compat_v2 are not used because the compatibility date enables the same behavior. Existing projects do not need to remove these flags when updating their compatibility date. To turn off Node.js compatibility completely, remove the positive flags if present. Then add both no_nodejs_compat and no_nodejs_compat_v2.

If you see errors using a particular npm package on Workers, you should first try updating your compatibility date and use the latest version of Wrangler CLI or the Cloudflare Vite Plugin. If you still encounter issues, please report them by opening a GitHub issue ↗︎.

Streams Constructors

Default as of 2022-11-30
Flag to enable streams_enable_constructors
Flag to disable streams_disable_constructors

Adds the work-in-progress new ReadableStream() and new WritableStream() constructors backed by JavaScript underlying sources and sinks.

Compliant TransformStream constructor

Default as of 2022-11-30
Flag to enable transformstream_enable_standard_constructor
Flag to disable transformstream_disable_standard_constructor

Previously, the new TransformStream() constructor was not compliant with the Streams API standard. Use the transformstream_enable_standard_constructor to opt-in to the backwards-incompatible change to make the constructor compliant. Must be used in combination with the streams_enable_constructors flag.

CommonJS modules do not export a module namespace

Default as of 2022-10-31
Flag to enable export_commonjs_default
Flag to disable export_commonjs_namespace

CommonJS modules were previously exporting a module namespace (an object like { default: module.exports }) rather than exporting only the module.exports. When this flag is enabled, the export is fixed.

Do not throw from async functions

Default as of 2022-10-31
Flag to enable capture_async_api_throws
Flag to disable do_not_capture_async_api_throws

The capture_async_api_throws compatibility flag will ensure that, in conformity with the standards API, async functions will only ever reject if they throw an error. The inverse do_not_capture_async_api_throws flag means that async functions which contain an error may throw that error synchronously rather than rejecting.

New URL parser implementation

Default as of 2022-10-31
Flag to enable url_standard
Flag to disable url_original

The original implementation of the URL ↗︎ API in Workers was not fully compliant with the WHATWG URL Standard ↗︎, differing in several ways, including:

  • The original implementation collapsed sequences of multiple slashes into a single slash:

new URL("https://example.com/a//b").toString() === "https://example.com/a/b" - The original implementation would throw "TypeError: Invalid URL string." if it encountered invalid percent-encoded escape sequences, like https://example.com/a%%b. - The original implementation would percent-encode or percent-decode certain content differently:

new URL("https://example.com/a%40b?c d%20e?f").toString() === "https://example.com/a@b?c+d+e%3Ff" - The original implementation lacked more recently implemented URL features, like URL.canParse() ↗︎.

Set the compatibility date of your Worker to a date after 2022-10-31 or enable the url_standard compatibility flag to opt-in the fully spec compliant URL API implementation.

Refer to the response_redirect_url_standard compatibility flag , which affects the URL implementation used in Response.redirect().

R2 bucket list respects the include option

Default as of 2022-08-04
Flag to enable r2_list_honor_include

With the r2_list_honor_include flag set, the include argument to R2 list options is honored. With an older compatibility date and without this flag, the include argument behaves implicitly as include: ["httpMetadata", "customMetadata"].

Do not substitute null on TypeError

Default as of 2022-06-01
Flag to enable dont_substitute_null_on_type_error
Flag to disable substitute_null_on_type_error

There was a bug in the runtime that meant that when being passed into built-in APIs, invalid values were sometimes mistakenly coalesced with null. Instead, a TypeError should have been thrown. The dont_substitute_null_on_type_error fixes this behavior so that an error is correctly thrown in these circumstances.

Minimal subrequests

Default as of 2022-04-05
Flag to enable minimal_subrequests
Flag to disable no_minimal_subrequests

With the minimal_subrequests flag set, fetch() subrequests sent to endpoints on the Worker's own zone (also called same-zone subrequests) have a reduced set of features applied to them. In general, these features should not have been initially applied to same-zone subrequests, and very few user-facing behavior changes are anticipated. Specifically, Workers might observe the following behavior changes with the new flag:

  • Response bodies will not be opportunistically gzipped before being transmitted to the Workers runtime. If a Worker reads the response body, it will read it in plaintext, as has always been the case, so disabling this prevents unnecessary decompression. Meanwhile, if the Worker passes the response through to the client, Cloudflare's HTTP proxy will opportunistically gzip the response body on that side of the Workers runtime instead. The behavior change observable by a Worker script should be that some Content-Encoding: gzip headers will no longer appear.
  • Automatic Platform Optimization may previously have been applied on both the Worker's initiating request and its subrequests in some circumstances. It will now only apply to the initiating request.
  • Link prefetching will now only apply to the Worker's response, not responses to the Worker's subrequests.
Default as of 2022-03-21
Flag to enable global_navigator
Flag to disable no_global_navigator

With the global_navigator flag set, a new global navigator property is available from within Workers. Currently, it exposes only a single navigator.userAgent property whose value is set to 'Cloudflare-Workers'. This property can be used to reliably determine whether code is running within the Workers environment.

Do not use the Custom Origin Trust Store for external subrequests

Default as of 2022-03-08
Flag to enable no_cots_on_external_fetch
Flag to disable cots_on_external_fetch

The no_cots_on_external_fetch flag disables the use of the Custom Origin Trust Store when making external (grey-clouded) subrequests from a Cloudflare Worker.

Setters/getters on API object prototypes

Default as of 2022-01-31
Flag to enable workers_api_getters_setters_on_prototype
Flag to disable workers_api_getters_setters_on_instance

Originally, properties on Workers API objects were defined as instance properties as opposed to prototype properties. This broke subclassing at the JavaScript layer, preventing a subclass from correctly overriding the superclass getters/setters. This flag controls the breaking change made to set those getters/setters on the prototype template instead.

This changes applies to:

  • AbortSignal
  • AbortController
  • Blob
  • Body
  • DigestStream
  • Event
  • File
  • Request
  • ReadableStream
  • ReadableStreamDefaultReader
  • ReadableStreamBYOBReader
  • Response
  • TextDecoder
  • TextEncoder
  • TransformStream
  • URL
  • WebSocket
  • WritableStream
  • WritableStreamDefaultWriter

Durable Object stub.fetch() requires a full URL

Default as of 2021-11-10
Flag to enable durable_object_fetch_requires_full_url
Flag to disable durable_object_fetch_allows_relative_url

Originally, when making a request to a Durable Object by calling stub.fetch(url), a relative URL was accepted as an input. The URL would be interpreted relative to the placeholder URL http://fake-host, and the resulting absolute URL was delivered to the destination object's fetch() handler. This behavior was incorrect — full URLs were meant to be required. This flag makes full URLs required.

fetch() improperly interprets unknown protocols as HTTP

Default as of 2021-11-10
Flag to enable fetch_refuses_unknown_protocols
Flag to disable fetch_treats_unknown_protocols_as_http

Originally, if the fetch() function was passed a URL specifying any protocol other than http: or https:, it would silently treat it as if it were http:. For example, fetch() would appear to accept ftp: URLs, but it was actually making HTTP requests instead.

Note that Cloudflare Workers supports a non-standard extension to fetch() to make it support WebSockets. However, when making an HTTP request that is intended to initiate a WebSocket handshake, you should still use http: or https: as the protocol, not ws: nor wss:.

The ws: and wss: URL schemes are intended to be used together with the new WebSocket() constructor, which exclusively supports WebSocket. The extension to fetch() is designed to support HTTP and WebSocket in the same request (the response may or may not choose to initiate a WebSocket), and so all requests are considered to be HTTP.

Streams BYOB reader detaches buffer

Default as of 2021-11-10
Flag to enable streams_byob_reader_detaches_buffer
Flag to disable streams_byob_reader_does_not_detach_buffer

Originally, the Workers runtime did not detach the ArrayBuffers from user-provided TypedArrays when using the BYOB reader's read() method, as required by the Streams spec, meaning it was possible to inadvertently reuse the same buffer for multiple read() calls. This change makes Workers conform to the spec.

User code should never try to reuse an ArrayBuffer that has been passed into a BYOB reader's read() method. Instead, user code can reuse the ArrayBuffer backing the result of the read() promise, as in the example below. 

// Consume and discard `readable` using a single 4KiB buffer.
let reader = readable.getReader({ mode: "byob" });
let arrayBufferView = new Uint8Array(4096);
while (true) {
  let result = await reader.read(arrayBufferView);
  if (result.done) break;
  // Optionally something with `result` here.
  // Re-use the same memory for the next `read()` by creating
  // a new Uint8Array backed by the result's ArrayBuffer.
  arrayBufferView = new Uint8Array(result.value.buffer);
}

The more recently added extension method readAtLeast() will always detach the ArrayBuffer and is unaffected by this feature flag setting.

FormData parsing supports File

Default as of 2021-11-03
Flag to enable formdata_parser_supports_files
Flag to disable formdata_parser_converts_files_to_strings

The FormData API ↗︎ is used to parse data (especially HTTP request bodies) in multipart/form-data format.

Originally, the Workers runtime's implementation of the FormData API incorrectly converted uploaded files to strings. Therefore, formData.get("filename") would return a string containing the file contents instead of a File object. This change fixes the problem, causing files to be represented using File as specified in the standard.

HTMLRewriter handling of <esi:include>

Flag to enable html_rewriter_treats_esi_include_as_void_tag

The HTML5 standard defines a fixed set of elements as void elements, meaning they do not use an end tag: <area>, <base>, <br>, <col>, <command>, <embed>, <hr>, <img>, <input>, <keygen>, <link>, <meta>, <param>, <source>, <track>, and <wbr>.