Adds documentation on DO shutdown #27482
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
size/s
product:durable-objects
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Contributor
|
Preview URL: https://1bb4f1cd.preview.developers.cloudflare.com Files with changes (up to 15) |
vy-ton
reviewed
Jan 12, 2026
|
|
||
| ## Shutdown behavior | ||
|
|
||
| Durable Objects may occasionally shut down and be replaced with a new instance. This can happen for various reasons, including: |
Contributor
There was a problem hiding this comment.
Suggested change
| Durable Objects may occasionally shut down and be replaced with a new instance. This can happen for various reasons, including: | |
| Durable Objects will occasionally shut down and objects are restarted, which will run your Durable Object class constructor. This can happen for various reasons, including: |
|
|
||
| Durable Objects may occasionally shut down and be replaced with a new instance. This can happen for various reasons, including: | ||
|
|
||
| - New deployments with code updates |
Contributor
There was a problem hiding this comment.
Suggested change
| - New deployments with code updates | |
| - New Worker [deployments](/workers/configuration/versions-and-deployments/) with code updates |
|
|
||
| - New deployments with code updates | ||
| - Updates to the Workers runtime system | ||
| - The runtime deciding to move the Durable Object to a different host |
Contributor
There was a problem hiding this comment.
Suggested change
| - The runtime deciding to move the Durable Object to a different host | |
| - Workers runtime decisions on where to host objects |
| - Updates to the Workers runtime system | ||
| - The runtime deciding to move the Durable Object to a different host | ||
|
|
||
| When a Durable Object is shut down, a new instance will come up automatically to handle new requests In-flight requests are handled as follows: |
Contributor
There was a problem hiding this comment.
Suggested change
| When a Durable Object is shut down, a new instance will come up automatically to handle new requests In-flight requests are handled as follows: | |
| When a Durable Object is shut down, the object instance is automatically restarted and new requests are routed to the new instance. In-flight requests are handled as follows: |
| Durable Objects may occasionally shut down and be replaced with a new instance. This can happen for various reasons, including: | ||
|
|
||
| - New deployments with code updates | ||
| - Updates to the Workers runtime system |
Contributor
There was a problem hiding this comment.
Suggested change
| - Updates to the Workers runtime system | |
| - Lack of requests to an object following the state transitions documented above | |
| - Cloudflare updates to the Workers runtime system |
|
|
||
| When a Durable Object is shut down, a new instance will come up automatically to handle new requests In-flight requests are handled as follows: | ||
|
|
||
| - **HTTP requests**: Requests are allowed to finish for up to 30 seconds. However, if a request attempts to access storage during this grace period, it will be stopped immediately, since storage access is now occurring on the new instance. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **HTTP requests**: Requests are allowed to finish for up to 30 seconds. However, if a request attempts to access storage during this grace period, it will be stopped immediately, since storage access is now occurring on the new instance. | |
| - **HTTP requests**: In-flight requests are allowed to finish for up to 30 seconds. However, if a request attempts to access a Durable Object's storage during this grace period, it will be stopped immediately to maintain Durable Objects global uniqueness property. |
@joshthoward does this also apply to RPC requests?
|
|
||
| When your Durable Object code is updated, your Worker and Durable Objects are released globally in an eventually consistent manner. This will cause a Durable Object to shut down, with the behavior described above. Updates can also create a situation where a request reaches a new version of your Worker in one location, and calls to a Durable Object still running a previous version elsewhere. Refer to [Code updates](/durable-objects/platform/known-issues/#code-updates) for more information about handling this scenario. | ||
|
|
||
| ### Working without shutdown hooks |
Contributor
There was a problem hiding this comment.
Let's put this in /durable-objects/best-practices/rules-of-durable-objects/#scheduling-and-lifecycle
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Not sure if I got the details exactly right, but thought that information on DO shutdown would be useful
Documentation checklist