Durable Objects code deferral becomes default behavior

Effective today, Durable Objects no longer switch to new code the instant you deploy. Instead, an active object can continue running its current version for up to five minutes (300 seconds) before it either hibernates and picks up the new version on the next request, or resets early if you request immediate adoption. The default deferral gives long‑running agents and WebSocket sessions a window to complete work, which matters to AI engineers, platform engineers, SREs, and security teams that rely on uninterrupted stateful processing.

How the deferral works

The update flow can be described as a simple decision tree:

You deploy new code → (default: deferred) → Object keeps running current code
   └─► Does it hibernate before the delay ends?
        ├─ Yes → Next request runs new code
        └─ No  → Object resets and adopts new code immediately

If you explicitly choose the immediate mode, the object resets as soon as the deployment reaches it, bypassing the delay.

Configuring the delay

The deferral period is controlled through the code_update_strategy block in your Wrangler configuration. You can set the mode to deferred (the default) or immediate, and adjust max_delay in seconds, from 0 up to 86 400 (24 hours) with millisecond precision. Omitting max_delay leaves the default of 300 seconds.

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

Both JSONC and TOML formats are supported; the snippet above shows the JSONC representation.

Operational considerations

• Deployment pipelines: CI/CD steps that previously assumed immediate code rollout must now account for the possible lag. Tests that verify version‑specific behavior should include a wait or a forced hibernation to ensure the new code is exercised.
• WebSocket stability: Objects that use the Hibernation API retain open connections across the deferral window, so long‑lived client sessions are less likely to be dropped during a rollout.
• Monitoring and alerts: Metrics that track object restarts may show a delayed spike after a deployment. Adjust alert thresholds to avoid false positives caused by the deferred reset.
• Security posture: The window where old code remains active could expose known bugs or misconfigurations until the object hibernates. Review any critical security patches to determine whether an immediate mode deployment is warranted.
• Resource usage: Objects that stay active longer may hold memory or CPU resources for the duration of the delay. Ensure capacity planning accounts for the maximum max_delay you configure.

Related CloudNinjas coverage: hands-on guides.

What This Means For Practitioners

Treat the default five‑minute deferral as a safety net for stateful workloads, but treat it as a configurable parameter rather than a guarantee. Align your deployment strategy with the latency tolerance of your services: use the default for most cases, switch to immediate when a security fix or critical bug cannot wait, and adjust max_delay when you need longer grace periods for complex shutdown logic. Update monitoring dashboards to surface the hibernation state and any delayed resets, and incorporate the deferral behavior into your incident‑response runbooks.