workerd

Compatibility Flags

Compability Flags allow you opt into changes to the Workers runtime. See the official Cloudflare documentation for more information.

These flags are automatically sourced from the workerd sourcecode, so may list flags that are not yet available. Usability of each flag is determined automatically every hour against the live Workers runtime, and can be noted below. If a flag is marked as usable, you can use it in wrangler.toml today.

NameDefault DateEnable FlagDisable FlagExperimentalUsable
cacheOptionEnabled N/A cache_option_enabled cache_option_disabled Experimental โŒ
newModuleRegistry N/A new_module_registry legacy_module_registry Experimental โŒ
globalFetchStrictlyPublic N/A global_fetch_strictly_public global_fetch_private_origin Experimental โŒ
nodeJsCompatV2 N/A nodejs_compat_v2 no_nodejs_compat_v2 Stable โœ…
Use standard URL parsing in `fetch()` 2024-06-03 fetch_standard_url fetch_legacy_url Stable โœ…
Properly extract blob MIME type from `content-type` headers 2024-06-03 blob_standard_mime_type blob_legacy_mime_type Stable โœ…
Returning empty Uint8Array on final BYOB read 2024-05-13 internal_stream_byob_return_view internal_stream_byob_return_undefined Stable โœ…
Durable Object stubs and Service Bindings support RPC 2024-04-03 rpc no_rpc Stable โœ…
Handling custom thenables 2024-04-01 unwrap_custom_thenables no_unwrap_custom_thenables Stable โœ…
Fetchers no longer have get/put/delete helper methods 2024-03-26 fetcher_no_get_put_delete fetcher_has_get_put_delete Stable โœ…
Python Workers N/A python_workers N/A Stable โœ…
Queues send messages in `JSON` format 2024-03-18 queues_json_messages no_queues_json_messages Stable โœ…
Node.js AsyncLocalStorage N/A nodejs_als no_nodejs_als Stable โœ…
Suppress global `importScripts()` 2024-03-04 no_global_importscripts global_importscripts Stable โœ…
jsRpc N/A js_rpc N/A Experimental โŒ
unsafeModule N/A unsafe_module N/A Experimental โŒ
`Vectorize` query with metadata optionally returned 2023-11-08 vectorize_query_metadata_optional vectorize_query_original Stable โœ…
WebCrypto preserve publicExponent field 2023-12-01 crypto_preserve_public_exponent no_crypto_preserve_public_exponent Stable โœ…
webgpu N/A webgpu N/A Experimental โŒ
rttiApi N/A rtti_api N/A Experimental โŒ
Strict crypto error checking 2023-08-01 strict_crypto_checks no_strict_crypto_checks Stable โœ…
Brotli Content-Encoding support 2024-04-29 brotli_content_encoding no_brotli_content_encoding Stable โœ…
Strict compression error checking 2023-08-01 strict_compression_checks no_strict_compression_checks Stable โœ…
URLSearchParams delete() and has() value argument 2023-07-01 urlsearchparams_delete_has_value_arg no_urlsearchparams_delete_has_value_arg Stable โœ…
Bot Management data 2023-08-01 no_cf_botmanagement_default cf_botmanagement_default Stable โœ…
serviceBindingExtraHandlers N/A service_binding_extra_handlers N/A Experimental โŒ
Dynamic Dispatch Exception Propagation 2023-03-01 dynamic_dispatch_tunnel_exceptions dynamic_dispatch_treat_exceptions_as_500 Stable โœ…
`Headers` supports `getSetCookie()` 2023-03-01 http_headers_getsetcookie no_http_headers_getsetcookie Stable โœ…
durableObjectGetExisting N/A durable_object_get_existing N/A Experimental โŒ
workerdExperimental N/A experimental N/A Experimental โŒ
Use a spec compliant URL implementation in redirects 2023-03-14 response_redirect_url_standard response_redirect_url_original Stable โœ…
obsolete22 N/A tcp_sockets_support N/A Stable โœ…
Node.js compatibility N/A nodejs_compat no_nodejs_compat Stable โœ…
WebSocket Compression 2023-08-15 web_socket_compression no_web_socket_compression Stable โœ…
obsolete19 N/A durable_object_rename N/A Experimental โŒ
CommonJS modules do not export a module namespace 2022-10-31 export_commonjs_default export_commonjs_namespace Stable โœ…
`R2` bucket `list` respects the `include` option 2022-08-04 r2_list_honor_include N/A Stable โœ…
Compliant TransformStream constructor 2022-11-30 transformstream_enable_standard_constructor transformstream_disable_standard_constructor Stable โœ…
Do not substitute `null` on `TypeError` 2022-06-01 dont_substitute_null_on_type_error substitute_null_on_type_error Stable โœ…
obsolete14 N/A durable_object_alarms N/A Stable โœ…
r2PublicBetaApi N/A r2_public_beta_bindings r2_internal_beta_bindings Stable โœ…
Do not throw from async functions 2022-10-31 capture_async_api_throws do_not_capture_async_api_throws Stable โœ…
Global `navigator` 2022-03-21 global_navigator no_global_navigator Stable โœ…
New URL parser implementation 2022-10-31 url_standard url_original Stable โœ…
Do not use the Custom Origin Trust Store for external subrequests 2022-03-08 no_cots_on_external_fetch cots_on_external_fetch Stable โœ…
Minimal subrequests 2022-04-05 minimal_subrequests no_minimal_subrequests Stable โœ…
Setters/getters on API object prototypes 2022-01-31 workers_api_getters_setters_on_prototype workers_api_getters_setters_on_instance Stable โœ…
Streams Constructors 2022-11-30 streams_enable_constructors streams_disable_constructors Stable โœ…
Streams BYOB reader detaches buffer 2021-11-10 streams_byob_reader_detaches_buffer streams_byob_reader_does_not_detach_buffer Stable โœ…
Durable Object `stub.fetch()` requires a full URL 2021-11-10 durable_object_fetch_requires_full_url durable_object_fetch_allows_relative_url Stable โœ…
`HTMLRewriter` handling of `<esi:include>` N/A html_rewriter_treats_esi_include_as_void_tag N/A Experimental โœ…
`fetch()` improperly interprets unknown protocols as HTTP 2021-11-10 fetch_refuses_unknown_protocols fetch_treats_unknown_protocols_as_http Stable โœ…
`FormData` parsing supports `File` 2021-11-03 formdata_parser_supports_files formdata_parser_converts_files_to_strings Stable โœ…

cacheOptionEnabled

Enable flag
cache_option_enabled
Disable flag
cache_option_disabled
Experimental
Yes
Publicly Documented
No
Usable
No

newModuleRegistry

Enable flag
new_module_registry
Disable flag
legacy_module_registry
Experimental
Yes
Publicly Documented
No
Usable
No

globalFetchStrictlyPublic

Enable flag
global_fetch_strictly_public
Disable flag
global_fetch_private_origin
Experimental
Yes
Publicly Documented
No
Usable
No

nodeJsCompatV2

Enable flag
nodejs_compat_v2
Disable flag
no_nodejs_compat_v2
Publicly Documented
No
Usable
Yes

Use standard URL parsing in `fetch()`

Default as of
2024-06-03
Enable flag
fetch_standard_url
Disable flag
fetch_legacy_url
Publicly Documented
Yes
Usable
Yes

The fetch_standard_url flag makes fetch() use WHATWG URL Standard parsing rules. The original implementation would throw TypeError: Fetch API cannot load errors with some URLs where standard parsing does not, for instance with the inclusion of whitespace before the URL. URL errors will now be thrown immediately upon calling new Request() with an improper URL. Previously, URL errors were thrown only once fetch() was called.

Properly extract blob MIME type from `content-type` headers

Default as of
2024-06-03
Enable flag
blob_standard_mime_type
Disable flag
blob_legacy_mime_type
Publicly Documented
Yes
Usable
Yes

When calling response.blob.type(), the MIME type will now be properly extracted from content-type headers, per the WHATWG spec.

Returning empty Uint8Array on final BYOB read

Default as of
2024-05-13
Enable flag
internal_stream_byob_return_view
Disable flag
internal_stream_byob_return_undefined
Publicly Documented
Yes
Usable
Yes

In the original implementation of BYOB ("Bring your own buffer") ReadableStreams, the read() method would return undefined when the stream was closed and there was no more data to read. This behavior was inconsistent with the standard ReadableStream behavior, which returns an empty Uint8Array when the stream is closed.

When the internal_stream_byob_return_view flag is used, the BYOB read() will implement standard behavior.

const resp = await fetch('https://example.org');
const reader = resp.body.getReader({ mode: 'byob' });
await result = await reader.read(new Uint8Array(10));

if (result.done) {
  // The result gives us an empty Uint8Array...
  console.log(result.value.byteLength); // 0

  // However, it is backed by the same underlying memory that was passed
  // into the read call.
  console.log(result.value.buffer.byteLength); // 10
}

Durable Object stubs and Service Bindings support RPC

Default as of
2024-04-03
Enable flag
rpc
Disable flag
no_rpc
Publicly Documented
Yes
Usable
Yes

With this flag on, Durable Object stubs and Service Bindings support RPC. This means that these objects now appear as if they define every possible method name. Calling any method name sends an RPC to the remote Durable Object or Worker service.

For most applications, this change will have no impact unless you use it. However, it's possible some existing code will be impacted if it explicitly checks for the existence of method names that were previously not defined on these types. For example, we've seen code in the wild which iterates over bindings and tries to auto-detect their types based on what methods they implement. Such code will now see service bindings as implementing every method, so may misinterpret service bindings as being some other type. In the cases we've seen, the impact was benign (nothing actually broke), but out of caution we are guarding this change behind a flag.

Handling custom thenables

Default as of
2024-04-01
Enable flag
unwrap_custom_thenables
Disable flag
no_unwrap_custom_thenables
Publicly Documented
Yes
Usable
Yes

With the unwrap_custom_thenables flag set, various Workers APIs that accept promises will also correctly handle custom thenables (objects with a then method) that are not native promises, but are intended to be treated as such). For example, the waitUntil method of the ExecutionContext object will correctly handle custom thenables, allowing them to be used in place of native promises.

async fetch(req, env, ctx) {
  ctx.waitUntil({ then(res) {
    // Resolve the thenable after 1 second
    setTimeout(res, 1000);
  } });
  // ...
}

Fetchers no longer have get/put/delete helper methods

Default as of
2024-03-26
Enable flag
fetcher_no_get_put_delete
Disable flag
fetcher_has_get_put_delete
Publicly Documented
Yes
Usable
Yes

Durable Object stubs and Service Bindings both implement a fetch() method which behaves similarly to the global fetch() method, but requests are instead sent to the destination represented by the object, rather than being routed based on the URL.

Historically, API objects that had such a fetch() method also had methods get(), put(), and delete(). These methods were thin wrappers around fetch() which would perform the corresponding HTTP method and automatically handle writing/reading the request/response bodies as needed.

These methods were a very early idea from many years ago, but were never actually documented, and therefore rarely (if ever) used. Enabling the fetcher_no_get_put_delete, or setting a compatibility date on or after 2024-03-26 disables these methods for your Worker.

This change paves a future path for you to be able to define your own custom methods using these names. Without this change, you would be unable to define your own get, put, and delete methods, since they would conflict with these built-in helper methods.

Python Workers

Enable flag
python_workers
Publicly Documented
Yes
Usable
Yes

This flag enables first class support for Python. Python Workers implement the majority of Python's standard library, support all bindings, environment variable, and secrets, and integration with JavaScript objects and functions via a foreign function interface.

Queues send messages in `JSON` format

Default as of
2024-03-18
Enable flag
queues_json_messages
Disable flag
no_queues_json_messages
Publicly Documented
Yes
Usable
Yes

With the queues_json_messages flag set, Queue bindings will serialize values passed to send() or sendBatch() into JSON format by default (when no specific contentType is provided).

Node.js AsyncLocalStorage

Enable flag
nodejs_als
Disable flag
no_nodejs_als
Publicly Documented
Yes
Usable
Yes

Enables the availability of the Node.js AsyncLocalStorage API in Workers. This API allows you to store data that is accessible to all asynchronous operations within a given execution context. This is useful for storing data that is relevant to the current request, such as request-specific metadata or tracing information.

Suppress global `importScripts()`

Default as of
2024-03-04
Enable flag
no_global_importscripts
Disable flag
global_importscripts
Publicly Documented
Yes
Usable
Yes

Suppresses the global importScripts() function. This method was included in the Workers global scope but was marked explicitly as non-implemented. However, the presence of the function could cause issues with some libraries. This compatibility flag removes the function from the global scope.

jsRpc

Enable flag
js_rpc
Experimental
Yes
Publicly Documented
No
Usable
No

unsafeModule

Enable flag
unsafe_module
Experimental
Yes
Publicly Documented
No
Usable
No

`Vectorize` query with metadata optionally returned

Default as of
2023-11-08
Enable flag
vectorize_query_metadata_optional
Disable flag
vectorize_query_original
Publicly Documented
Yes
Usable
Yes

A set value on vectorize_query_metadata_optional indicates that the Vectorize query operation should accept newer arguments with returnValues and returnMetadata specified discretely over the older argument returnVectors. This also changes the return format. If the vector values have been indicated for return, the return value is now a flattened vector object with score attached where it previously contained a nested vector object.

WebCrypto preserve publicExponent field

Default as of
2023-12-01
Enable flag
crypto_preserve_public_exponent
Disable flag
no_crypto_preserve_public_exponent
Publicly Documented
Yes
Usable
Yes

In the WebCrypto API, the publicExponent field of the algorithm of RSA keys would previously be an ArrayBuffer. Using this flag, publicExponent is a Uint8Array as mandated by the specification.

webgpu

Enable flag
webgpu
Experimental
Yes
Publicly Documented
No
Usable
No

rttiApi

Enable flag
rtti_api
Experimental
Yes
Publicly Documented
No
Usable
No

Strict crypto error checking

Default as of
2023-08-01
Enable flag
strict_crypto_checks
Disable flag
no_strict_crypto_checks
Publicly Documented
Yes
Usable
Yes

Perform additional error checking in the Web Crypto API to conform with the specification and reject possibly unsafe key parameters:

  • For RSA key generation, key sizes are required to be multiples of 128 bits as boringssl may otherwise truncate the key.
  • The size of imported RSA keys must be at least 256 bits and at most 16384 bits, as with newly generated keys.
  • The public exponent for imported RSA keys is restricted to the commonly used values [3, 17, 37, 65537].
  • In conformance with the specification, an error will be thrown when trying to import a public ECDH key with non-empty usages.

Brotli Content-Encoding support

Default as of
2024-04-29
Enable flag
brotli_content_encoding
Disable flag
no_brotli_content_encoding
Publicly Documented
Yes
Usable
Yes

When the brotli_content_encoding compatibility flag is enabled, Workers supports the br content encoding and can request and respond with data encoded using the Brotli compression algorithm. This reduces the amount of data that needs to be fetched and can be used to pass through the original compressed data to the client. See the Fetch API documentation for details.

Strict compression error checking

Default as of
2023-08-01
Enable flag
strict_compression_checks
Disable flag
no_strict_compression_checks
Publicly Documented
Yes
Usable
Yes

Perform additional error checking in the Compression Streams API and throw an error if a DecompressionStream has trailing data or gets closed before the full compressed data has been provided.

URLSearchParams delete() and has() value argument

Default as of
2023-07-01
Enable flag
urlsearchparams_delete_has_value_arg
Disable flag
no_urlsearchparams_delete_has_value_arg
Publicly Documented
Yes
Usable
Yes

The WHATWG introduced additional optional arguments to the URLSearchParams object delete() and has() methods that allow for more precise control over the removal of query parameters. Because the arguments are optional and change the behavior of the methods when present there is a risk of breaking existing code. If your compatibility date is set to July 1, 2023 or after, this compatibility flag will be enabled by default.

For an example of how this change could break existing code, consider code that uses the Array forEach() method to iterate through a number of parameters to delete:

const usp = new URLSearchParams();
// ...
['abc', 'xyz'].forEach(usp.delete.bind(usp));

The forEach() automatically passes multiple parameters to the function that is passed in. Prior to the addition of the new standard parameters, these extra arguments would have been ignored.

Now, however, the additional arguments have meaning and change the behavior of the function. With this flag, the example above would need to be changed to:

const usp = new URLSearchParams();
// ...
['abc', 'xyz'].forEach((key) => usp.delete(key));

Bot Management data

Default as of
2023-08-01
Enable flag
no_cf_botmanagement_default
Disable flag
cf_botmanagement_default
Publicly Documented
Yes
Usable
Yes

This flag streamlines Workers requests by reducing unnecessary properties in the request.cf object.

With the flag enabled - either by default after 2023-08-01 or by setting the no_cf_botmanagement_default flag - Cloudflare will only include the Bot Management object in a Worker's request.cf if the account has access to Bot Management.

With the flag disabled, Cloudflare will include a default Bot Management object, regardless of whether the account is entitled to Bot Management.

serviceBindingExtraHandlers

Enable flag
service_binding_extra_handlers
Experimental
Yes
Publicly Documented
No
Usable
No

Dynamic Dispatch Exception Propagation

Default as of
2023-03-01
Enable flag
dynamic_dispatch_tunnel_exceptions
Disable flag
dynamic_dispatch_treat_exceptions_as_500
Publicly Documented
Yes
Usable
Yes

Previously, when using Workers for Platforms' dynamic dispatch API to send an HTTP request to a user Worker, if the user Worker threw an exception, the dynamic dispatch Worker would receive an HTTP 500 error with no body. When the dynamic_dispatch_tunnel_exceptions compatibility flag is enabled, the exception will instead propagate back to the dynamic dispatch Worker. The fetch() call in the dynamic dispatch Worker will throw the same exception. This matches the similar behavior of service bindings and Durable Objects.

`Headers` supports `getSetCookie()`

Default as of
2023-03-01
Enable flag
http_headers_getsetcookie
Disable flag
no_http_headers_getsetcookie
Publicly Documented
Yes
Usable
Yes

Adds the getSetCookie() method to the Headers API in Workers.

const response = await fetch("https://example.com");
let cookieValues = response.headers.getSetCookie();

durableObjectGetExisting

Enable flag
durable_object_get_existing
Experimental
Yes
Publicly Documented
No
Usable
No

workerdExperimental

Enable flag
experimental
Experimental
Yes
Publicly Documented
No
Usable
No

Use a spec compliant URL implementation in redirects

Default as of
2023-03-14
Enable flag
response_redirect_url_standard
Disable flag
response_redirect_url_original
Publicly Documented
Yes
Usable
Yes

Change the URL implementation used in Response.redirect() to be spec-compliant (WHATWG URL Standard).

obsolete22

Enable flag
tcp_sockets_support
Publicly Documented
No
Usable
Yes

Node.js compatibility

Enable flag
nodejs_compat
Disable flag
no_nodejs_compat
Publicly Documented
Yes
Usable
Yes

Enables the full set of available Node.js APIs in the Workers Runtime.

WebSocket Compression

Default as of
2023-08-15
Enable flag
web_socket_compression
Disable flag
no_web_socket_compression
Publicly Documented
Yes
Usable
Yes

The Workers runtime did not support WebSocket compression when the initial WebSocket implementation was released. Historically, the runtime has stripped or ignored the Sec-WebSocket-Extensions header -- but is now capable of fully complying with the WebSocket Compression RFC. Since many clients are likely sending Sec-WebSocket-Extensions: permessage-deflate to their Workers today (new WebSocket(url) automatically sets this in browsers), we have decided to maintain prior behavior if this flag is absent.

If the flag is present, the Workers runtime is capable of using WebSocket Compression on both inbound and outbound WebSocket connections.

Like browsers, calling new WebSocket(url) in a Worker will automatically set the Sec-WebSocket-Extensions: permessage-deflate header. If you are using the non-standard fetch() API to obtain a WebSocket, you can include the Sec-WebSocket-Extensions header with value permessage-deflate and include any of the compression parameters defined in RFC-7692.

obsolete19

Enable flag
durable_object_rename
Experimental
Yes
Publicly Documented
No
Usable
No

CommonJS modules do not export a module namespace

Default as of
2022-10-31
Enable flag
export_commonjs_default
Disable flag
export_commonjs_namespace
Publicly Documented
Yes
Usable
Yes

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.

`R2` bucket `list` respects the `include` option

Default as of
2022-08-04
Enable flag
r2_list_honor_include
Publicly Documented
Yes
Usable
Yes

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"].

Compliant TransformStream constructor

Default as of
2022-11-30
Enable flag
transformstream_enable_standard_constructor
Disable flag
transformstream_disable_standard_constructor
Publicly Documented
Yes
Usable
Yes

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.

Do not substitute `null` on `TypeError`

Default as of
2022-06-01
Enable flag
dont_substitute_null_on_type_error
Disable flag
substitute_null_on_type_error
Publicly Documented
Yes
Usable
Yes

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.

obsolete14

Enable flag
durable_object_alarms
Publicly Documented
No
Usable
Yes

r2PublicBetaApi

Enable flag
r2_public_beta_bindings
Disable flag
r2_internal_beta_bindings
Publicly Documented
No
Usable
Yes

Do not throw from async functions

Default as of
2022-10-31
Enable flag
capture_async_api_throws
Disable flag
do_not_capture_async_api_throws
Publicly Documented
Yes
Usable
Yes

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.

Global `navigator`

Default as of
2022-03-21
Enable flag
global_navigator
Disable flag
no_global_navigator
Publicly Documented
Yes
Usable
Yes

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.

New URL parser implementation

Default as of
2022-10-31
Enable flag
url_standard
Disable flag
url_original
Publicly Documented
Yes
Usable
Yes

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

Do not use the Custom Origin Trust Store for external subrequests

Default as of
2022-03-08
Enable flag
no_cots_on_external_fetch
Disable flag
cots_on_external_fetch
Publicly Documented
Yes
Usable
Yes

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.

Minimal subrequests

Default as of
2022-04-05
Enable flag
minimal_subrequests
Disable flag
no_minimal_subrequests
Publicly Documented
Yes
Usable
Yes

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.

Setters/getters on API object prototypes

Default as of
2022-01-31
Enable flag
workers_api_getters_setters_on_prototype
Disable flag
workers_api_getters_setters_on_instance
Publicly Documented
Yes
Usable
Yes

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

Streams Constructors

Default as of
2022-11-30
Enable flag
streams_enable_constructors
Disable flag
streams_disable_constructors
Publicly Documented
Yes
Usable
Yes

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

Streams BYOB reader detaches buffer

Default as of
2021-11-10
Enable flag
streams_byob_reader_detaches_buffer
Disable flag
streams_byob_reader_does_not_detach_buffer
Publicly Documented
Yes
Usable
Yes

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.

Durable Object `stub.fetch()` requires a full URL

Default as of
2021-11-10
Enable flag
durable_object_fetch_requires_full_url
Disable flag
durable_object_fetch_allows_relative_url
Publicly Documented
Yes
Usable
Yes

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 dummy URL http://fake-host, and the resulting absolute URL was delivered to the destination object's fetch() handler. This was a mistake โ€” full URLs were meant to be required. This flag makes full URLs required.

`HTMLRewriter` handling of `<esi:include>`

Enable flag
html_rewriter_treats_esi_include_as_void_tag
Experimental
Yes
Publicly Documented
Yes
Usable
Yes

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

HTML5 does not recognize XML self-closing tag syntax. For example, <script src="foo.js" /> does not specify a script element with no body. A </script> ending tag is still required. The /> syntax simply is not recognized by HTML5 at all and it is treated the same as >. However, many developers still like to use this syntax, as a holdover from XHTML, a standard which failed to gain traction in the early 2000's.

<esi:include> and <esi:comment> are two tags that are not part of the HTML5 standard, but are instead used as part of Edge Side Includes, a technology for server-side HTML modification. These tags are not expected to contain any body and are commonly written with XML self-closing syntax.

HTMLRewriter was designed to parse standard HTML5, not ESI. However, it would be useful to be able to implement some parts of ESI using HTMLRewriter. To that end, this compatibility flag causes HTMLRewriter to treat <esi:include> and <esi:comment> as void tags, so that they can be parsed and handled properly.

`fetch()` improperly interprets unknown protocols as HTTP

Default as of
2021-11-10
Enable flag
fetch_refuses_unknown_protocols
Disable flag
fetch_treats_unknown_protocols_as_http
Publicly Documented
Yes
Usable
Yes

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.

`FormData` parsing supports `File`

Default as of
2021-11-03
Enable flag
formdata_parser_supports_files
Disable flag
formdata_parser_converts_files_to_strings
Publicly Documented
Yes
Usable
Yes

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.

Flag descriptions are licensed under CC BY 4.0 and sourced from the cloudflare-docsrepository.