Version overrides

You can use version overrides to send a request to a specific version of your Worker in the current deployment, even those set to serve 0% of traffic.

To specify a version override in your request, set the Cloudflare-Workers-Version-Overrides header on the request to your Worker. Cloudflare-Workers-Version-Overrides is a Dictionary Structured Header ↗ that 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 ↗. For example:

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

There are a number of reasons why a request's version override may not be applied. For example:

• The deployment may not contain the specified version. It can take up to a couple of seconds to be available globally after a recent change.
• The header value may not be a valid Dictionary ↗.

In the case that a request's version override is not applied, the request will be routed according to the percentages set in the gradual deployment configuration.

You can observe the version of your Worker that was invoked using Observability ↗, including in features such as Logpush. Alternatively, if you want to inform clients about the version they ran (e.g. for faster and more transparent debugging), you could use the version metadata binding and return the version ID in the Worker's response.

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:

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

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

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

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:

// 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);
	},
};

// The override header from the inbound request is forwarded to the downstream Worker.
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		return env.MY_SERVICE.fetch(request);
	},
};

Alternatively, you can set an override header explicitly:

// 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;
	},
};

// Replace the version ID with the target version from `wrangler versions list`.
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		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;
	},
};

• Version affinity - Use cookies & headers to pin users to a specific version during a gradual deployment.
• Gradual deployments - Learn how percentage-based traffic splitting works.
• Service bindings - How Workers communicate with each other.
• Version metadata binding - Access version ID and tag from within your Worker.