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"'A version must be in a deployment before an override can select it. Its traffic percentage can be 0%:
| Deployment at the location handling the request | Traffic by default | With a version override |
|---|---|---|
| Only A; B has been uploaded | A | An override for B is ignored because B is outside the deployment. The request uses A. |
| A at 100%, B at 0% | A | An override can select B and its assets. |
| A at 0%, B at 100% | B | An override can still select A. |
| Only B | B | An override for A is ignored, even if A remains in version history. The request uses B. |
You can also turn on a Version URL to access an uploaded version. This does not require adding it to the production deployment.
Deployment changes take time to reach every location on the network. A location ignores an override if its deployment does not yet include the requested version. It uses the configured traffic percentages instead. Refer to Version skew and static assets before using overrides for related requests.
There are a number of reasons why a request's version override may not be applied. For example:
- The deployment at the location handling the request may not include the version. This can happen while a deployment change spreads across the network.
- 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.
Use Observability, including Logpush, to check which Worker version handled a request. Alternatively, use the version metadata binding to return the version ID in the response. Check the version as well as the status code. An ignored override can still return a successful response.
To keep HTML and asset requests on the same version, include the HTML's Worker version ID in each asset URL. A Request Header Transform Rule can turn that ID into a version override.
For example, version A contains /assets/a.js and version B contains /assets/b.js. Both versions belong to the deployment. B's HTML can request B's asset even when the location handling the asset request still has B at 0%:
sequenceDiagram
participant Browser
participant HTML as Location serving HTML
participant Assets as Location serving the asset
Browser->>HTML: GET /
HTML-->>Browser: B's HTML, with B's ID in the script URL
Browser->>Assets: GET /assets/b.js?__worker_version=B
Note over Assets: Deployment: A at 100%, B at 0%
Note over Assets: Transform Rule sets override for B
Assets-->>Browser: b.js from B
In this diagram, B represents the full Worker version ID.
This approach requires a proxied hostname on your Cloudflare zone. The Transform Rule does not run on workers.dev.
-
Include the version ID in asset URLs.
Configure the version metadata binding and assets binding. This example runs the Worker for
/to generate HTML:{ "version_metadata": { "binding": "CF_VERSION_METADATA" }, "assets": { "directory": "./public", "binding": "ASSETS", "run_worker_first": ["/"] } }[version_metadata] binding = "CF_VERSION_METADATA" [assets] directory = "./public" binding = "ASSETS" run_worker_first = [ "/" ]In version B, place
b.jsinpublic/assets/. Read the serving version's ID when generating its script URL:export default { async fetch(request, env) { if (new URL(request.url).pathname === "/") { const version = encodeURIComponent(env.CF_VERSION_METADATA.id); return new Response( `<!doctype html> <html lang="en"> <meta charset="utf-8"> <title>Version B</title> <script src="/assets/b.js?__worker_version=${version}"></script> </html>`, { headers: { "content-type": "text/html; charset=utf-8" } }, ); } return env.ASSETS.fetch(request); }, };interface Env { CF_VERSION_METADATA: WorkerVersionMetadata; ASSETS: Fetcher; } export default { async fetch(request, env): Promise<Response> { if (new URL(request.url).pathname === "/") { const version = encodeURIComponent(env.CF_VERSION_METADATA.id); return new Response( `<!doctype html> <html lang="en"> <meta charset="utf-8"> <title>Version B</title> <script src="/assets/b.js?__worker_version=${version}"></script> </html>`, { headers: { "content-type": "text/html; charset=utf-8" } }, ); } return env.ASSETS.fetch(request); }, } satisfies ExportedHandler<Env>;Version A uses the same pattern with
/assets/a.js. Each version reads its own ID, so older HTML keeps requesting that version's assets. -
Set the override before Cloudflare selects the Worker version.
The query parameter alone does not select a version. Create a Request Header Transform Rule with this filter expression. Replace the hostname and two version IDs with your values:
(http.host eq "example.com" and starts_with(http.request.uri.path, "/assets/") and http.request.uri.args["__worker_version"][0] in { "db7cd8d3-4425-4fe7-8c81-01bf963b6067" "dc8dcd28-271b-4367-9840-6c244f84cb40" })Select Set dynamic for the
Cloudflare-Workers-Version-Overridesheader. Use this value expression, replacingmy-workerwith your Worker name:concat("my-worker=\"", http.request.uri.args["__worker_version"][0], "\"")For a request with B's version ID, the rule produces:
Cloudflare-Workers-Version-Overrides: my-worker="dc8dcd28-271b-4367-9840-6c244f84cb40"The override selects B and its assets before asset routing runs. Setting the header inside the selected Worker's handler does not change which version handles that request.
-
Keep both versions in the deployment.
Use a gradual deployment to add B at 0% before sending normal traffic to it. Then promote B while keeping A at 0%:
flowchart LR Stage["A at 100%, B at 0%"] --> Wait["Allow deployment to propagate"] Wait --> Promote["A at 0%, B at 100%"] Promote --> Old["Older HTML requests A's assets"] Promote --> New["New HTML requests B's assets"]Deployment changes take up to a few seconds to propagate. If the receiving location still has a deployment containing only A, an override for B is ignored. A fixed wait or a check at one location does not prove that every location includes B.
Apply the version ID to every related asset URL, including imported JavaScript chunks, stylesheets, and URLs within CSS. A script's query string does not carry over to files it imports.
Keep the Transform Rule's allowed version IDs in sync with your deployment. When you later replace A with C, pages loaded from A can no longer select their version.
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 ID | Percentage |
|---|---|
| db7cd8d3-4425-4fe7-8c81-01bf963b6067 | 100% |
Create a new deployment using wrangler versions deploy and specify 0% for the new version whilst keeping the previous version at 100%.
| Version ID | Percentage |
|---|---|
| dc8dcd28-271b-4367-9840-6c244f84cb40 | 0% |
| db7cd8d3-4425-4fe7-8c81-01bf963b6067 | 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 - Keep requests with the same key on one version while the deployment configuration stays the same.
- Version skew and static assets - Understand deployment propagation and asset availability across releases.
- 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.