Skip to content
Cloudflare Docs

Lifecycle of a Durable Object

This section describes the lifecycle of a Durable Object.

To use a Durable Object you need to create a Durable Object Stub. Simply creating the Durable Object Stub does not send a request to the Durable Object, and therefore the Durable Object is not yet instantiated. A request is sent to the Durable Object and its lifecycle begins only once a method is invoked on the Durable Object Stub.

const id = env.MY_DURABLE_OBJECT.idFromName("foo");
const stub = env.MY_DURABLE_OBJECT.get(id);
// Now the request is sent to the remote Durable Object.
const rpcResponse = await stub.sayHello();

Durable Object Lifecycle state transitions

A Durable Object can be in one of the following states at any moment:

StateDescription
Active, in-memoryThe Durable Object runs, in memory, and handles incoming requests.
Idle, in-memory non-hibernateableThe Durable Object waits for the next incoming request/event, but does not satisfy the criteria for hibernation.
Idle, in-memory hibernateableThe Durable Object waits for the next incoming request/event and satisfies the criteria for hibernation. It is up to the runtime to decide when to hibernate the Durable Object. Currently, it is after 10 seconds of inactivity while in this state.
HibernatedThe Durable Object is removed from memory. Hibernated WebSocket connections stay connected.
InactiveThe Durable Object is completely removed from the host process and might need to cold start. This is the initial state of all Durable Objects.

This is how a Durable Object transitions among these states (each state is in a rounded rectangle).

Lifecycle of a Durable Object

Assuming a Durable Object does not run, the first incoming request or event (like an alarm) will execute the constructor() of the Durable Object class, then run the corresponding function invoked.

At this point the Durable Object is in the active in-memory state.

If it continuously receives requests or events within 10 seconds of each other, the Durable Object will remain in this state.

Once all incoming requests or events have been processed, the Durable Object remains idle in-memory for a few seconds either in a hibernateable state or in a non-hibernateable state.

Hibernation can only occur if all of the conditions below are true:

  • No setTimeout/setInterval scheduled callbacks are set, since there would be no way to recreate the callback after hibernating.
  • No in-progress awaited fetch() exists, since it is considered to be waiting for I/O.
  • No WebSocket standard API is used.
  • No request/event is still being processed, because hibernating would mean losing track of the async function which is eventually supposed to return a response to that request.

After 10 seconds of no incoming request or event, and all the above conditions satisfied, the Durable Object will transition into the hibernated state.

If any of the above conditions is false, the Durable Object remains in-memory, in the idle, in-memory, non-hibernateable state.

In case of an incoming request or event while in the hibernated state, the constructor() will run again, and the Durable Object will transition to the active, in-memory state and execute the invoked function.

While in the idle, in-memory, non-hibernateable state, after 70-140 seconds of inactivity (no incoming requests or events), the Durable Object will be evicted entirely from memory and potentially from the Cloudflare host and transition to the inactive state.

Objects in the hibernated state keep their Websocket clients connected, and the runtime decides if and when to transition the object to the inactive state (for example deciding to move the object to a different host) thus restarting the lifecycle.

The next incoming request or event starts the cycle again.