Changelog

Durable Objects can stay active across requests, allowing you to run long-running agents, maintain long-lived WebSocket connections and coordinate state across many clients. This is possible because each Durable Object is globally unique, and this means it must run only one version of your code at a time. Previously, when you deployed a change to your Durable Objects code, that change would be applied immediately, which could interrupt in-flight work and terminate open connections.

You can now set a Durable Object's code update strategy to deferred, which tells Cloudflare to wait for the Durable Object to hibernate before it applies the update. This lets in-flight work finish before code updates and keeps open WebSocket connections that use the Hibernation API connected.

Add code_update_strategy to durable_objects in your Wrangler configuration:

{
	"durable_objects": {
		"bindings": [
			{
				"name": "CHAT_ROOM",
				"class_name": "ChatRoom",
			},
		],
		"code_update_strategy": {
			"mode": "deferred",
			"max_delay": 60,
		},
	},
}

[[durable_objects.bindings]]
name = "CHAT_ROOM"
class_name = "ChatRoom"

[durable_objects.code_update_strategy]
mode = "deferred"
max_delay = 60

max_delay is in seconds, up to a maximum of 300 (five minutes). Omit it to use the default for your compatibility date. Set mode to immediate — or pass --durable-objects-code-update-mode immediate for a single deployment — to apply an update right away, for example during an incident:

npx wrangler versions deploy <VERSION_ID>@100% --durable-objects-code-update-mode immediate

yarn wrangler versions deploy <VERSION_ID>@100% --durable-objects-code-update-mode immediate

pnpm wrangler versions deploy <VERSION_ID>@100% --durable-objects-code-update-mode immediate

A deferred code update is best-effort, not a guarantee. Cloudflare can still reset an object before max_delay is reached.

For more information, including how this interacts with gradual deployments and the REST API, refer to Durable Objects code updates.