Skip to content

Known issues

Last updated View as MarkdownAgent setup

Durable Objects is generally available. However, there are some known issues.

Global uniqueness

Global uniqueness guarantees there is only a single instance of a Durable Object class with a given ID running at once, across the world.

Uniqueness is enforced upon starting a new event (such as receiving an HTTP request), and upon accessing storage.

After an event is received, if the event takes some time to execute and does not ever access its durable storage, then it is possible that the Durable Object may no longer be current, and some other instance of the same Durable Object ID will have been created elsewhere. If the event accesses storage at this point, it will receive an exception. If the event completes without ever accessing storage, it may not ever realize that the Durable Object was no longer current.

A Durable Object may be replaced in the event of a network partition or a software update (including either an update of the Durable Object's class code, or of the Workers system itself). Enabling wrangler tail or Cloudflare dashboard ↗︎ logs requires a software update.

Code updates

Code changes for Workers and Durable Objects are released globally in an eventually consistent manner. A request can reach the latest version of your Worker, which then calls a unique Durable Object running a previous version of your code.

With a deferred code update strategy, an active Durable Object can continue running a previous version until it hibernates or its max_delay is reached. Gradual deployments can extend this window while your deployment uses more than one version. If you deploy multiple versions before an object hibernates, it might skip intermediate versions and use the latest version when it wakes.

Ensure that API changes between your Workers and Durable Objects are forward and backward compatible across code updates.

Development tools

wrangler tail logs from requests that are upgraded to WebSockets are delayed until the WebSocket is closed. wrangler tail should not be connected to a Worker that you expect will receive heavy volumes of traffic.

The Workers editor in the Cloudflare dashboard ↗︎ allows you to interactively edit and preview your Worker and Durable Objects. In the editor, Durable Objects can only be talked to by a preview request if the Worker being previewed both exports the Durable Object class and binds to it. Durable Objects exported by other Workers cannot be talked to in the editor preview.

wrangler dev has read access to Durable Object storage, but writes will be kept in memory and will not affect persistent data. However, if you specify the script_name explicitly in the Durable Object binding, then writes will affect persistent data. Wrangler will emit a warning in that case.

Alarms in local development

Currently, when developing locally (using npx wrangler dev), Durable Object alarm methods may fail after a hot reload (if you edit the code while the code is running locally).

To avoid this issue, when using Durable Object alarms, close and restart your wrangler dev command after editing your code.

Was this helpful?