A Durable Object chat room accepts every socket with ctx.acceptWebSocket(), yet its duration charges show it awake around the clock; what keeps it from hibernating?
answer
- every condition must hold
- timers cannot be recreated
- pending I/O, up to 15 minutes
- outbound sockets never hibernate
- one standard-API socket
basics
~20 sSomething else pins it in memory: a pending setTimeout() or setInterval(), unfinished I/O or ctx.waitUntil() promises, an open outbound connection such as an upstream WebSocket, any socket accepted with ws.accept(), or an event that never finishes.
solid answer
~40 sHibernation is all-or-nothing: an idle object is eligible only when no `setTimeout()` or `setInterval()` callback is pending, no I/O or `ctx.waitUntil()` promise is unfinished, no outbound connection is open, no socket uses the standard `accept()` API, and no request or event is still running. The usual culprits in a chat room are a presence or heartbeat `setInterval()`, an outbound WebSocket to an upstream feed (outbound sockets never hibernate), a fire-and-forget `fetch()` passed to `waitUntil()`, or one old code path still calling `ws.accept()`. While any of them holds, the object is billed for wall-clock duration at 128 MB. Find the blocker by searching the class for timers, outbound connections and `accept()`, then move periodic work to a storage alarm, let the auto-response answer heartbeats, and keep long-lived upstream connections out of the room object.
go deeper
Recall that ctx.acceptWebSocket() makes hibernation possible but does not force it; timers and open I/O keep the object awake.
List the conditions: no pending timers, no unfinished I/O or waitUntil() promises, no open outbound connection, no standard-API socket, no running event.
Diagnose from billing, find the blocker in code, reproduce with an idle gap, and replace it: alarms for periodic work, auto-responses for heartbeats, upstream connections moved out.
Make hibernation-safety a review checklist item for every WebSocket object, because one stray timer turns a traffic-shaped bill into an always-on one.
## The conditions for hibernation Accepting sockets with `this.ctx.acceptWebSocket()` makes hibernation possible; it does not make it happen. An idle Durable Object can hibernate only when every one of these is true: 1. No `setTimeout()` or `setInterval()` callback is pending, since the runtime could not recreate it after eviction. 2. No I/O operation or promise passed to `this.ctx.waitUntil()` is unfinished, and no outbound connection is open. 3. No socket uses the standard WebSocket API, that is, nothing was accepted with `ws.accept()`. 4. No request or event is still being processed. When all of them hold, the runtime currently hibernates the object after about 10 seconds without events, and it bills no duration from the moment the object is idle and eligible. When any one fails, the object stays in memory in the idle, non-hibernateable state and is billed for wall-clock duration at 128 MB. Eligibility is decided for the whole object, which is why one blocker anywhere in the class defeats it, however many sockets are handled correctly. ## Usual culprits in a chat room | Culprit | Why it blocks | Replacement | |---|---|---| | `setInterval()` for presence or heartbeats | a pending timer cannot survive eviction | a storage alarm, or client heartbeats answered by `setWebSocketAutoResponse()` | | an outbound WebSocket to an upstream feed | outbound sockets never hibernate | move the upstream connection out of the room | | `this.ctx.waitUntil(fetch(...))` for analytics | pending I/O holds the object | send it from the Worker in front | | one code path still calling `ws.accept()` | any standard-API socket blocks | `this.ctx.acceptWebSocket()` everywhere | | a handler awaiting a call that never settles | the event never finishes | timeouts on outbound calls, or `setHibernatableWebSocketEventTimeout()` | ## How long each blocker holds the object - A pending timer makes the object ineligible for as long as it is pending, and a `setInterval()` stays pending until it is cleared. - Each pending I/O operation, such as an outbound `fetch()`, a service binding or RPC call, a promise passed to `waitUntil()`, a TCP socket or an outbound WebSocket, prevents eviction until it completes or for up to 15 minutes from its start, whichever comes first. - Operations started together do not add up their windows, but an operation started later can extend the object's time in memory, so a steady trickle of upstream traffic can keep it there indefinitely. - A standard-API socket keeps the object billable for as long as it is connected. - While any blocker holds, duration accrues even though no handler is running. ## How to find the blocker 1. Confirm the symptom: duration that stays high around the clock while request counts rise and fall with traffic. 2. Search the class for `setInterval`, `setTimeout`, `waitUntil`, `fetch(`, `new WebSocket(`, `connect(` and `.accept(`. 3. Reproduce locally. `wrangler dev` hibernates objects too, so log a line in the constructor, leave a socket idle for 15 seconds, then send a message. A second constructor line means the object hibernated; none means something held it. 4. Remove the blockers one at a time and repeat the idle test until the constructor line appears. The idle test is worth keeping as a regression check: a later change that adds a timer or an outbound call fails it immediately, long before the bill shows it. ## Fixes that keep the room hibernating - **Periodic work goes to a storage alarm.** An alarm is stored durably, wakes the object when it is due, and is not among the conditions that block hibernation. - **Heartbeats go to the runtime.** Clients send them, and `this.ctx.setWebSocketAutoResponse()` answers them without waking the object. - **Upstream feeds leave the room.** One dedicated object can hold the outbound connection and push updates to the rooms, so only that object stays awake instead of every room. - **Outbound calls get timeouts**, so one hung request cannot pin the object for 15 minutes at a time. - **Every socket is accepted with `this.ctx.acceptWebSocket()`**, including the ones on old code paths. The general lesson is that hibernation is a property of the whole object, not of the sockets: one stray timer or connection anywhere in the class turns a bill that follows traffic back into an always-on one.
- Why does a pending setInterval() block hibernation when a scheduled storage alarm does not?A timer callback lives only in the instance's memory, and the runtime has no way to recreate it after evicting the object, so the object has to stay. An alarm is stored with the object's durable state, and the runtime calls `alarm()` when it is due, waking the object if it has to.
- The room relays an upstream feed over an outbound WebSocket; how do you stop that from pinning every room?Outbound WebSockets never hibernate, and each open one prevents eviction for up to 15 minutes from its start, with later I/O able to extend that. Move the upstream connection into one dedicated object that pushes updates to the rooms, so only that object stays in memory and the rooms' accepted sockets can hibernate.
- Believes ctx.acceptWebSocket() alone guarantees the object will hibernate.
- Uses setInterval() in the object for presence updates and still expects hibernation.
- Thinks outbound WebSockets the object opens hibernate like accepted ones.
- Assumes an idle object eligible for hibernation is billed until it is actually evicted.
- Expects waitUntil() work to be dropped when the object would otherwise hibernate.