Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Version overrides

You can use version overrides to send a request to a specific version of your Worker in your gradual deployment.

To specify a version override in your request, set the Cloudflare-Workers-Version-Overrides header on the request to your Worker. For example:

Terminal window
curl -s https://example.com -H 'Cloudflare-Workers-Version-Overrides: my-worker-name="dc8dcd28-271b-4367-9840-6c244f84cb40"'

Cloudflare-Workers-Version-Overrides is a Dictionary Structured Header ↗.

The dictionary can contain multiple key-value pairs. Each key indicates the name of the Worker the override should be applied to. The value indicates the version ID that should be used and must be a String ↗.

A version override will only be applied if the specified version is in the current deployment. The versions in the current deployment can be found using the wrangler deployments list command or on the Workers & Pages page of the Cloudflare dashboard > select your Worker > Deployments > Active Deployment ↗.

Example

You may want to test a new version in production before gradually deploying it to an increasing proportion of external traffic. This is commonly referred to as a "smoke test".

In this example, your deployment is initially configured to route all traffic to a single version:

Version IDPercentage
db7cd8d3-4425-4fe7-8c81-01bf963b6067100%

Create a new deployment using wrangler versions deploy and specify 0% for the new version whilst keeping the previous version at 100%.

Version IDPercentage
dc8dcd28-271b-4367-9840-6c244f84cb400%
db7cd8d3-4425-4fe7-8c81-01bf963b6067100%

Now test the new version with a version override before gradually progressing the new version to 100%:

Terminal window
curl -s https://example.com -H 'Cloudflare-Workers-Version-Overrides: my-worker-name="dc8dcd28-271b-4367-9840-6c244f84cb40"'

Service bindings

You can set the Cloudflare-Workers-Version-Overrides header when making a subrequest from one Worker to another using a service binding. This lets you test a specific version of a downstream Worker from an upstream Worker.

If you forward the original request object, the override header carries through automatically:

JavaScript
// The override header from the inbound request is forwarded to the downstream Worker.
export default {
  async fetch(request, env) {
    return env.MY_SERVICE.fetch(request);
  },
};

Alternatively, you can set an override header explicitly:

JavaScript
// Replace the version ID with the target version from `wrangler versions list`.
export default {
  async fetch(request, env) {
    const response = await env.MY_SERVICE.fetch("https://example.com/", {
      headers: {
        "Cloudflare-Workers-Version-Overrides":
          'my-downstream-worker="dc8dcd28-271b-4367-9840-6c244f84cb40"',
      },
    });
    return response;
  },
};