Covers the expected, documented behaviour that a code update terminates a Durable Object's WebSockets, and gradual deployments extending the window this can happen in. Does not cover WebSocket drops unrelated to deploys (idle timeouts, client network loss, or missing ping/pong handling) — rule those out first if the disconnects don't line up with a deploy.
Unverifiedno reproductions yetWhy this confidence?8 steps. Every step is written out below in full — the interactive version simply follows the branches for you.
Every WebSocket connected to a Durable Object closes when that Durable Object's code is updated, because Cloudflare restarts the object to run the new code.
What happens next
Compare deployment timestamps against WebSocket close events to rule out an unrelated cause (idle timeout, client network loss).
npx wrangler deployments listExpected result
WebSocket close events cluster within seconds of a deployment timestamp.What happens next
With gradual deployments, traffic is split across old and new Worker versions over an extended rollout window. A Durable Object can be restarted more than once during that window as traffic shifts, and a request on the new version can reach a Durable Object still momentarily running the old one.
npx wrangler deployments listExpected result
A deployment showing a percentage rollout (e.g. 10% → 100% over time) rather than an instant 100% cutover.What happens next
If the timing doesn't correlate with deployments, look at idle timeouts, missing ping/pong keep-alive handling, or client-side network conditions instead — this playbook only covers the deploy-triggered reset.
During a gradual deployment, code changes are released globally in an eventually-consistent manner, so a request can hit the new Worker version while its Durable Object is still on the old one for a short period. Ensure the RPC/API surface between them is compatible in both directions for the duration of the rollout, in addition to adding client reconnect logic.
What happens next
A code-update-triggered disconnect is expected platform behaviour, not a bug to eliminate. Design the client to detect the close and reconnect automatically (with backoff), and use the Hibernation API (server.accept()) so the Durable Object itself doesn't need to hold the connection object in memory between messages — that reduces unrelated evictions, though it does not prevent a disconnect caused by an actual code update.
function connect() {
const ws = new WebSocket("wss://your-worker.example.workers.dev/room");
ws.addEventListener("close", () => {
setTimeout(connect, 1000 + Math.random() * 1000);
});
return ws;
}What happens next
Deploy with the reconnect logic in place and confirm connected clients reconnect within your expected window instead of the application breaking.
Changes system or service state. Review before running.
Deploys the new Worker/Durable Object code to production, which will itself trigger the same reset being tested for.
npx wrangler deployExpected result
Clients briefly disconnect and reconnect automatically within a second or two of the deploy, with no application-level errors.What happens next
Clients now recover automatically from the disconnect that deploys inherently cause.
What would strengthen it: 6 more independent reproductions. Reproductions from 3 more distinct environments.