Durable Objects, Workers - Durable Objects now defer code updates by default

<p>Durable Objects can stay active across requests, allowing you to run long-running <a href="https://developers.cloudflare.com/agents/">agents</a>, maintain <a href="https://developers.cloudflare.com/durable-objects/best-practices/websockets/">long-lived WebSocket connections</a> 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.</p> <p>Durable Objects now defer code updates by default. When you deploy, an active Durable Object can keep running its current code for up to 5 minutes (300 seconds) while it waits to hibernate. This gives in-flight work time to finish. WebSocket connections that use the <a href="https://developers.cloudflare.com/durable-objects/examples/websocket-hibernation-server/">Hibernation API</a> remain connected when an object adopts new code after hibernating.</p> <p>For an active Durable Object, a code update follows this flow:</p> <pre class="mermaid">flowchart TD accTitle: Code updates for an active Durable Object accDescr: By default, an active object can keep running its current code until it hibernates or the delay ends. After hibernating, it starts on new code on the next request. If the delay ends first, or immediate mode is selected, it resets and adopts the new code. Deferral is best effort. A["You deploy new code"] --&gt;|"Default: deferred"| B["The object can keep running&lt;br/&gt;its current code"] B --&gt; C{"Hibernates before&lt;br/&gt;the delay ends?"} C --&gt;|Yes| D["Starts on the new code&lt;br/&gt;on the next request"] C --&gt;|No| E["The object resets&lt;br/&gt;and adopts the new code"] A -.-&gt;|"Override: immediate"| E </pre> <p>To change the delay, add <code>code_update_strategy</code> to <code>durable_objects</code> in your Wrangler configuration:</p> <div data-nb-tabs data-nb-sync-key="wranglerConfig" class><div class="relative flex border-b border-border" role="tablist" data-nb-tabs-list><span class="bg-primary pointer-events-none absolute -bottom-px h-0.5 rounded-t-sm transition-[left,width] duration-200 ease-out" data-nb-tabs-indicator aria-hidden="true"></span></div><div class="mt-3"><div role="tabpanel" data-nb-tabs-content data-nb-tab-label="wrangler.jsonc" class><figure class="nb-code-figure" data-nb-lang="jsonc"><pre class="astro-code astro-code-themes github-light github-dark nb-shiki-c6xiwz" tabindex="0" data-language="jsonc" data-nb-lang="jsonc"><code><span class="line"><span class="nb-shiki-140thh">{</span></span> <span class="line"><span class="nb-shiki-dzsirb"> "durable_objects"</span><span class="nb-shiki-140thh">: {</span></span> <span class="line"><span class="nb-shiki-dzsirb"> "bindings"</span><span class="nb-shiki-140thh">: [</span></span> <span class="line"><span class="nb-shiki-140thh"> {</span></span> <span class="line"><span class="nb-shiki-dzsirb"> "name"</span><span class="nb-shiki-140thh">: </span><span class="nb-shiki-mdbnqw">"CHAT_ROOM"</span><span class="nb-shiki-140thh">,</span></span> <span class="line"><span class="nb-shiki-dzsirb"> "class_name"</span><span class="nb-shiki-140thh">: </span><span class="nb-shiki-mdbnqw">"ChatRoom"</span><span class="nb-shiki-140thh">,</span></span> <span class="line"><span class="nb-shiki-140thh"> },</span></span> <span class="line"><span class="nb-shiki-140thh"> ],</span></span> <span class="line"><span class="nb-shiki-dzsirb"> "code_update_strategy"</span><span class="nb-shiki-140thh">: {</span></span> <span class="line"><span class="nb-shiki-dzsirb"> "mode"</span><span class="nb-shiki-140thh">: </span><span class="nb-shiki-mdbnqw">"deferred"</span><span class="nb-shiki-140thh">,</span></span> <span class="line"><span class="nb-shiki-dzsirb"> "max_delay"</span><span class="nb-shiki-140thh">: </span><span class="nb-shiki-dzsirb">60</span><span class="nb-shiki-140thh">,</span></span> <span class="line"><span class="nb-shiki-140thh"> },</span></span> <span class="line"><span class="nb-shiki-140thh"> },</span></span> <span class="line"><span class="nb-shiki-140thh">}</span></span></code></pre></figure></div><div role="tabpanel" data-nb-tabs-content data-nb-tab-label="wrangler.toml" class><figure class="nb-code-figure" data-nb-lang="toml"><pre class="astro-code astro-code-themes github-light github-dark nb-shiki-c6xiwz" tabindex="0" data-language="toml" data-nb-lang="toml"><code><span class="line"><span class="nb-shiki-140thh">[[</span><span class="nb-shiki-1t8gfj">durable_objects</span><span class="nb-shiki-140thh">.</span><span class="nb-shiki-1t8gfj">bindings</span><span class="nb-shiki-140thh">]]</span></span> <span class="line"><span class="nb-shiki-140thh">name = </span><span class="nb-shiki-mdbnqw">"CHAT_ROOM"</span></span> <span class="line"><span class="nb-shiki-140thh">class_name = </span><span class="nb-shiki-mdbnqw">"ChatRoom"</span></span> <span class="line"></span> <span class="line"><span class="nb-shiki-140thh">[</span><span class="nb-shiki-1t8gfj">durable_objects</span><span class="nb-shiki-140thh">.</span><span class="nb-shiki-1t8gfj">code_update_strategy</span><span class="nb-shiki-140thh">]</span></span> <span class="line"><span class="nb-shiki-140thh">mode = </span><span class="nb-shiki-mdbnqw">"deferred"</span></span> <span class="line"><span class="nb-shiki-140thh">max_delay = </span><span class="nb-shiki-dzsirb">60</span></span></code></pre></figure></div></div></div><script type="module" src="https://developers.cloudflare.com/home/runner/work/cloudflare-docs/cloudflare-docs/src/components/ui/tabs/Tabs.astro?astro&type=script&index=0&lang.ts"></script> <p><code>max_delay</code> is in seconds, from <code>0</code> to <code>86400</code> (24 hours), with millisecond precision. Omit it to use the default of <code>300</code> seconds.</p> <p>To set the strategy for a single deployment, pass <code>--durable-objects-code-update-mode</code> with <code>immediate</code> or <code>deferred &lt;duration&gt;</code>. For example, apply an update right away during an incident, or when your deployment tooling calls a Durable Object right after deploying and needs the new code:</p> <script> if (!customElements.get("nb-pm-restore")) { customElements.define( "nb-pm-restore", class extends HTMLElement { connectedCallback() { const card = this.closest("[data-nb-pm]"); if (!card) return; let saved; try { saved = sessionStorage.getItem("ui-pm-tab"); } catch { return; } if (!saved) return; const tabs = card.querySelectorAll("[data-nb-pm-tab]"); let idx = -1; tabs.forEach(function (t, i) { if (t.textContent.trim() === saved) idx = i; }); if (idx < 1) return; tabs.forEach(function (t, i) { t.setAttribute("aria-selected", String(i === idx)); }); card.querySelectorAll("[data-nb-pm-panel]").forEach(function (p, i) { p.hidden = i !== idx; }); } }, ); } </script><div data-nb-pm class="w-full"><div class="flex w-full flex-col overflow-hidden rounded-lg text-sm ring ring-border bg-card"><div class="flex items-center gap-2 px-3 py-2 text-[0.8125rem] font-medium leading-5 text-muted-foreground bg-[var(--nb-surface-sunken)]" role="tablist" aria-label="Package manager"><button role="tab" type="button" aria-selected="true" aria-controls="pm-panel-pm-5f29ef2a-npm" id="pm-tab-pm-5f29ef2a-npm" data-nb-pm-tab class="text-muted-foreground hover:bg-accent hover:text-foreground aria-selected:bg-selected aria-selected:text-foreground focus-visible:outline-ring m-0 cursor-pointer rounded-md border-0 bg-transparent px-2 py-0.5 text-xs leading-5 font-medium transition-colors focus-visible:outline-2 focus-visible:outline-offset-2">npm</button><button role="tab" type="button" aria-selected="false" aria-controls="pm-panel-pm-5f29ef2a-yarn" id="pm-tab-pm-5f29ef2a-yarn" data-nb-pm-tab class="text-muted-foreground hover:bg-accent hover:text-foreground aria-selected:bg-selected aria-selected:text-foreground focus-visible:outline-ring m-0 cursor-pointer rounded-md border-0 bg-transparent px-2 py-0.5 text-xs leading-5 font-medium transition-colors focus-visible:outline-2 focus-visible:outline-offset-2">yarn</button><button role="tab" type="button" aria-selected="false" aria-controls="pm-panel-pm-5f29ef2a-pnpm" id="pm-tab-pm-5f29ef2a-pnpm" data-nb-pm-tab class="text-muted-foreground hover:bg-accent hover:text-foreground aria-selected:bg-selected aria-selected:text-foreground focus-visible:outline-ring m-0 cursor-pointer rounded-md border-0 bg-transparent px-2 py-0.5 text-xs leading-5 font-medium transition-colors focus-visible:outline-2 focus-visible:outline-offset-2">pnpm</button></div><div role="tabpanel" id="pm-panel-pm-5f29ef2a-npm" aria-labelledby="pm-tab-pm-5f29ef2a-npm" data-nb-pm-panel class="bg-card ring-border relative overflow-hidden rounded-lg text-inherit ring"><div class="flex items-stretch"><pre class="text-foreground my-0 min-w-0 grow overflow-x-auto border-0 bg-transparent px-4 py-3 font-mono text-sm leading-relaxed whitespace-pre"><code data-nb-pm-code><span class="text-success">npx</span><span class="text-warning"> wrangler versions deploy &lt;VERSION_ID&gt;@100% --durable-objects-code-update-mode immediate</span></code></pre><button type="button" data-nb-pm-copy data-nb-command="npx wrangler versions deploy <VERSION_ID>@100% --durable-objects-code-update-mode immediate" aria-label="Copy to clipboard" class="border-border text-muted-foreground hover:text-foreground focus-visible:outline-ring m-0 flex shrink-0 cursor-pointer items-center justify-center border-0 border-l border-solid bg-transparent px-3 transition-colors focus-visible:outline-2 focus-visible:-outline-offset-2"><svg width="1em" height="1em" viewBox="0 0 256 256" class="h-[18px] w-[18px]" data-icon="ph:copy"><path fill="currentColor" d="M216 32H88a8 8 0 0 0-8 8v40H40a8 8 0 0 0-8 8v128a8 8 0 0 0 8 8h128a8 8 0 0 0 8-8v-40h40a8 8 0 0 0 8-8V40a8 8 0 0 0-8-8m-56 176H48V96h112Zm48-48h-32V88a8 8 0 0 0-8-8H96V48h112Z"/></svg><svg width="1em" height="1em" viewBox="0 0 256 256" class="hidden h-[18px] w-[18px]" data-icon="ph:check"><path fill="currentColor" d="m229.66 77.66l-128 128a8 8 0 0 1-11.32 0l-56-56a8 8 0 0 1 11.32-11.32L96 188.69L218.34 66.34a8 8 0 0 1 11.32 11.32"/></svg></button></div></div><div role="tabpanel" id="pm-panel-pm-5f29ef2a-yarn" aria-labelledby="pm-tab-pm-5f29ef2a-yarn" hidden data-nb-pm-panel class="bg-card ring-border relative overflow-hidden rounded-lg text-inherit ring"><div class="flex items-stretch"><pre class="text-foreground my-0 min-w-0 grow overflow-x-auto border-0 bg-transparent px-4 py-3 font-mono text-sm leading-relaxed whitespace-pre"><code data-nb-pm-code><span class="text-success">yarn</span><span class="text-warning"> wrangler versions deploy &lt;VERSION_ID&gt;@100% --durable-objects-code-update-mode immediate</span></code></pre><button type="button" data-nb-pm-copy data-nb-command="yarn wrangler versions deploy <VERSION_ID>@100% --durable-objects-code-update-mode immediate" aria-label="Copy to clipboard" class="border-border text-muted-foreground hover:text-foreground focus-visible:outline-ring m-0 flex shrink-0 cursor-pointer items-center justify-center border-0 border-l border-solid bg-transparent px-3 transition-colors focus-visible:outline-2 focus-visible:-outline-offset-2"><svg width="1em" height="1em" viewBox="0 0 256 256" class="h-[18px] w-[18px]" data-icon="ph:copy"><path fill="currentColor" d="M216 32H88a8 8 0 0 0-8 8v40H40a8 8 0 0 0-8 8v128a8 8 0 0 0 8 8h128a8 8 0 0 0 8-8v-40h40a8 8 0 0 0 8-8V40a8 8 0 0 0-8-8m-56 176H48V96h112Zm48-48h-32V88a8 8 0 0 0-8-8H96V48h112Z"/></svg><svg width="1em" height="1em" viewBox="0 0 256 256" class="hidden h-[18px] w-[18px]" data-icon="ph:check"><path fill="currentColor" d="m229.66 77.66l-128 128a8 8 0 0 1-11.32 0l-56-56a8 8 0 0 1 11.32-11.32L96 188.69L218.34 66.34a8 8 0 0 1 11.32 11.32"/></svg></button></div></div><div role="tabpanel" id="pm-panel-pm-5f29ef2a-pnpm" aria-labelledby="pm-tab-pm-5f29ef2a-pnpm" hidden data-nb-pm-panel class="bg-card ring-border relative overflow-hidden rounded-lg text-inherit ring"><div class="flex items-stretch"><pre class="text-foreground my-0 min-w-0 grow overflow-x-auto border-0 bg-transparent px-4 py-3 font-mono text-sm leading-relaxed whitespace-pre"><code data-nb-pm-code><span class="text-success">pnpm</span><span class="text-warning"> wrangler versions deploy &lt;VERSION_ID&gt;@100% --durable-objects-code-update-mode immediate</span></code></pre><button type="button" data-nb-pm-copy data-nb-command="pnpm wrangler versions deploy <VERSION_ID>@100% --durable-objects-code-update-mode immediate" aria-label="Copy to clipboard" class="border-border text-muted-foreground hover:text-foreground focus-visible:outline-ring m-0 flex shrink-0 cursor-pointer items-center justify-center border-0 border-l border-solid bg-transparent px-3 transition-colors focus-visible:outline-2 focus-visible:-outline-offset-2"><svg width="1em" height="1em" viewBox="0 0 256 256" class="h-[18px] w-[18px]" data-icon="ph:copy"><path fill="currentColor" d="M216 32H88a8 8 0 0 0-8 8v40H40a8 8 0 0 0-8 8v128a8 8 0 0 0 8 8h128a8 8 0 0 0 8-8v-40h40a8 8 0 0 0 8-8V40a8 8 0 0 0-8-8m-56 176H48V96h112Zm48-48h-32V88a8 8 0 0 0-8-8H96V48h112Z"/></svg><svg width="1em" height="1em" viewBox="0 0 256 256" class="hidden h-[18px] w-[18px]" data-icon="ph:check"><path fill="currentColor" d="m229.66 77.66l-128 128a8 8 0 0 1-11.32 0l-56-56a8 8 0 0 1 11.32-11.32L96 188.69L218.34 66.34a8 8 0 0 1 11.32 11.32"/></svg></button></div></div><nb-pm-restore style="display:contents"></nb-pm-restore></div></div><script type="module" src="https://developers.cloudflare.com/home/runner/work/cloudflare-docs/cloudflare-docs/src/components/ui/package-managers/PackageManagerTabs.astro?astro&type=script&index=0&lang.ts"></script> <p>A <code>deferred</code> code update is best effort and does not guarantee that every operation finishes. The object can still reset before <code>max_delay</code> is reached, for example during a Cloudflare runtime update.</p> <p>For more information, including how this interacts with gradual deployments and the REST API, refer to <a href="https://developers.cloudflare.com/durable-objects/deployments/durable-objects-code-updates/">Durable Objects code updates</a>.</p>