Storage
Durable Objects
Run Cloudflare Durable Objects on OpenOrange, where each object is one Rivet Actor with its own SQLite database.
Runs on Rivet Actors with SQLite storage and alarms
- Works
- SQL and key-value storage, transactions, alarms, RPC,
fetch(), and WebSockets, through the samecloudflare:workersAPI - Differs
- An idle object loses its instance fields after 10 seconds
- Missing
stub.connect(), point-in-time recovery, read replication, andctx.props- Migration
- Live migration Each SQLite-backed object moves on its first request to Orange, and a backfill moves the rest. KV-backed classes (
new_classes) cannot move. Migration guide
- Configure
durable_objectsmigrations- Scales by
- Object ID
- Checks
- 6 pass · 2 partial
Each Durable Object runs as one Rivet Actor
with its own SQLite database. Your class and your wrangler.jsonc run
unchanged.
Quickstart
This builds examples/hello-durable-object,
a Greeter object for each name that counts its visits.
-
Bind the class
Add a binding and a migration to
wrangler.jsonc. Every class needs one migration that creates it.{ "name": "hello-durable-object", "main": "src/index.ts", "compatibility_date": "2026-09-03", "durable_objects": { "bindings": [{ "name": "GREETER", "class_name": "Greeter" }] }, "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Greeter"] }] } -
Write the class
Extend
DurableObjectand export the class from your entry file. A migration runs no SQL, so create your tables in the constructor.import { DurableObject } from "cloudflare:workers"; export class Greeter extends DurableObject<Env> { constructor(ctx: DurableObjectState, env: Env) { super(ctx, env); ctx.storage.sql.exec( "CREATE TABLE IF NOT EXISTS visits (visited_at INTEGER NOT NULL)", ); } sayHello(name: string): { greeting: string; visits: number } { const sql = this.ctx.storage.sql; sql.exec("INSERT INTO visits (visited_at) VALUES (?)", Date.now()); const { visits } = sql .exec<{ visits: number }>("SELECT count(*) AS visits FROM visits") .one(); return { greeting: `Hello, ${name}!`, visits }; } } -
Call it from your Worker
getByName()sends every request for one name to the same object. Call its methods over RPC like local functions.export default { async fetch(request, env): Promise<Response> { const name = new URL(request.url).pathname.slice(1) || "World"; const stub = env.GREETER.getByName(name); return Response.json(await stub.sayHello(name)); }, } satisfies ExportedHandler<Env>; -
Run it
orange devshows each Durable Object binding as a Rivet Actor.orange dev Binding Resource Runs on env.GREETER Durable Object Rivet Actor · Greeter ● Ready in 5.3s Local http://127.0.0.1:8787Each name is its own object, and its count survives a restart of
orange dev:curl localhost:8787/alice {"greeting":"Hello, alice!","visits":1} curl localhost:8787/alice {"greeting":"Hello, alice!","visits":2} curl localhost:8787/bob {"greeting":"Hello, bob!","visits":1}
How it works
- Your class instance runs inside the actor, and
ctx.storagereads and writes the actor’s database. - When the object is idle, Orange drops the instance and builds a new one on
the next request, RPC call, alarm, or message. Keep state in
ctx.storage, not in fields. - An open WebSocket stays connected while the instance is gone.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
| Feature | Status | Notes |
|---|---|---|
idFromName(), newUniqueId(), idFromString(), get(), getByName(), jurisdiction() | Supported | Location hints and jurisdictions are checked, but they do not change where an object runs. |
| Method RPC on a stub | Supported | Streams, RpcTarget, callbacks, and pipelined calls work. A class that does not extend DurableObject gets fetch() and alarms, but no RPC. |
stub.fetch() | Supported | Request and response bodies stream. |
stub.connect() | Not supported | Throws. Service binding connect() works. |
ctx.storage.sql | Supported | A cursor reads all its rows before it returns. |
ctx.storage.kv and the async storage API | Supported | |
transactionSync() and transaction() | Supported | |
| Alarms | Supported | |
getCurrentBookmark(), waitForBookmark() | Supported | Bookmarks use the local workerd format. |
getBookmarkForTime(), onNextSessionRestoreBookmark() | Not supported | Reading one throws a NotSupportedError. |
snapshot(), onNextSessionRestore() | Not supported | Reading one throws a NotSupportedError. |
ensureReplicas(), disableReplicas() | Not supported | Reading one throws a NotSupportedError. |
blockConcurrencyWhile(), waitUntil(), abort() | Supported | abort() restarts the whole Rivet Actor. |
ctx.exports | Supported | |
| Standard WebSockets | Supported | |
| WebSocket hibernation API | Partial | Emulated. See WebSocket hibernation. |
ctx.facets | Partial | get(), abort(), delete(), and clone(): the part that the agents SDK uses. See Facets. |
ctx.container | Partial | Runs only Cloudflare Sandbox images. See Sandbox. |
ctx.props, ctx.restore, ctx.configureReadReplication, ctx.primaryStub, ctx.version | Not supported | Reading one throws a NotSupportedError. |
Limits
Orange does not copy Cloudflare’s quotas, such as its limits on WebSocket tags, sockets per object, and attachment size. Rivet’s limits apply:
| What | Limit | What happens over it |
|---|---|---|
| One storage write | 128 MiB of changed SQLite pages in one commit | The write throws a RangeError that names the limit. |
| One RPC call | 32 MiB on the wire. Binary data counts 4/3 of its size. | The call throws a RangeError. Send large data with stub.fetch(), which streams. |
blockConcurrencyWhile() | 30 seconds | The object resets. |
| Idle time before the instance or actor stops | 10 seconds | See Lifecycle. |
| Alarm retries | 6 | The alarm is dropped. |
| Facet depth | 4, including the root | clone() does nothing at the maximum depth. |
| Awake objects on one runner | 4,000 by default. Set RIVET__PEGBOARD__SQLITE_SESSIONS to change it. | The next object does not start. See One runner holds at most 4,000 awake objects. |
| Storage per object | No limit set by Orange |
All synchronous SQL runs on the one Node.js runtime thread, so a long query delays the other Workers and objects in that process.
Configuration
Orange reads the binding and migrations as wrangler dev does, with these
differences:
In wrangler.jsonc | On Orange |
|---|---|
new_sqlite_classes | Creates the class, with SQLite storage. |
new_classes | The same. Orange stores every class in SQLite, so these classes can use SQL too. |
renamed_classes | The class keeps its objects. |
deleted_classes | The class goes away. Its objects’ data stays in storage. |
transferred_classes | The class starts empty. Orange does not move the objects that the other Worker stored. |
| Any other migration field | orange dev stops with an error. |
A binding with script_name | Works when that Worker runs in the same orange dev session. See Multiple Workers. |
A binding with environment or namespace_id | Loads as a stub that throws when you use it. |
- More than one binding can name one class.
- A migrated class with no binding is still registered. Reach it through
ctx.exportsor theexportsimport fromcloudflare:workers. - A bound class with no migration that creates it stops
orange devwith an error. - RPC to a plain class that does not extend
DurableObjectfails, also with thejs_rpcflag, because Orange does not read compatibility flags.
To move objects that already hold data on Cloudflare, see Migrate from Cloudflare.
Lifecycle
The instance of your class lives inside the object’s Rivet Actor. The instance and the actor stop at different times:
- With an open WebSocket, Orange drops the instance after 10 seconds without an event. The actor and the socket stay, and the next message builds a new instance. See WebSocket hibernation.
- Without one, the actor sleeps after 10 seconds without an event. The next request, RPC call, or alarm wakes it.
- Either way, instance fields are lost. An idle object stops sooner than on Cloudflare.
For how Orange builds each part, see the implementation notes.
What keeps an object awake
These keep the instance running past the idle timeout, as in wrangler dev:
- A standard WebSocket.
- A WebSocket that the object opened, while it is open.
- A
fetch()until its response headers arrive, also when nothing awaits it. - An open RPC session, or an RPC result that a caller still holds.
- A
waitUntil()orctx.keepAwake()task. - A pending
setTimeout()orsetInterval()callback, until it runs or you clear it.unref()does not change that. The timers ofnode:timersandnode:timers/promisesare the global timers, so they count too. - An upgrade that a client has not claimed yet.
For the measurements, see the implementation notes.
- A pending timer, an outbound WebSocket, or a
fetch()also keeps an object that has no WebSocket. Orange keeps its actor awake until the work ends, so the timer runs in the same instance. - Only work that your Worker code starts counts. The timers and sockets of Orange and its packages do not keep an object awake.
- When
ctx.abort()resets an object, or its actor stops, Orange cancels the timers of the old instance, as workerd does. Their callbacks never run against an instance that is gone. - An interval that is never cleared keeps the instance and its Rivet Actor
awake with or without a socket. The actor keeps its memory and counts toward
the runner’s
limit of awake objects.
Clear each
setInterval()when the object has no more work for it.
When the runtime stops, it closes each accepted WebSocket with
1012 Service Restart, at random times in a window of 10 ms per socket, up to
10 seconds. Clients do not all reconnect at once. Standard WebSockets close at
once.
Find what keeps an object awake
Orange prints one line for each hibernation event of an object when RivetKit’s
info logs are on. Run orange dev --log-level info, or set
RIVET_LOG_LEVEL=info for orange serve.
[durable-object] soft hibernation actor_id=<id> event=hibernated
[durable-object] soft hibernation actor_id=<id> event=woke
[durable-object] soft hibernation actor_id=<id> event=held class=Room idle_ms=10004 held_by=timer:1 timers=setInterval(3000ms):1The held line means that no event of the object started or ended for the
idle timeout, and the object still runs.
idle_msis the time since the last event started or ended. For a handler that still runs, it is how long the handler has run.held_bynames each cause with its count.
| Cause | What holds the object |
|---|---|
timer | A pending setTimeout() or setInterval() callback. timers lists each kind with its delay and count. |
standard-websocket | An open WebSocket that the object accepted with accept(). |
outbound-websocket | An open WebSocket that the object opened, with new WebSocket() or through a Durable Object stub. |
fetch | A fetch() whose response has not arrived. |
wait-until | A ctx.waitUntil() promise that has not settled. |
event | A request, message, or alarm handler that still runs. |
rpc-session | An open RPC session with a caller. |
rpc-result | An RPC result that a caller has not collected. It expires after 30 seconds. |
unclaimed-upgrade | A WebSocket upgrade whose client has not connected. It expires after 30 seconds. |
keep-awake | Work that Orange runs for the object, such as a Workflow step. |
When Orange prints the line:
- First when the idle time reaches 10 seconds, then at 20, 40, and so on. The interval doubles up to 10 minutes.
- An event that starts or ends starts the sequence again, so the next line comes 10 seconds after it.
- A
setInterval()that is never cleared shows in everyheldline, for as long as the object runs, asheld_by=timer:1 timers=setInterval(3000ms):1. - Only for an object that has a WebSocket. An object with no WebSocket prints
no
heldline, and with info logs, its actor’s sleep never appears.
Without info logs, Orange counts the causes and starts no report timer.
Storage
SQL
ctx.storage.sql.exec()runs synchronously on the actor’s SQLite database. Cursors supportnext(),toArray(),one(), raw rows, and duplicate column names.- SQL errors carry SQLite’s message and result code, as in workerd, for example
no such table: x: SQLITE_ERROR. databaseSizeuses workerd’s formula: allocated pages minus free pages, times the page size.- The cursor reads all rows before it returns.
rowsReadcounts returned rows, not scanned rows.rowsWrittencounts the changes of oneINSERT,UPDATE,DELETE, orREPLACE, and is 0 otherwise. - A script with more than one statement runs every statement and returns the rows of each. Workerd returns the last statement’s rows. Bindings on such a script are rejected.
BEGIN,COMMIT,ROLLBACK,SAVEPOINT, andRELEASEthroughexec()fail. UsetransactionSync()ortransaction().
Key-value storage
ctx.storage.kvhas synchronousget(),put(),delete(), andlist()on the same database and transaction as SQL.- The async API has
get(),put(),delete(),list(), anddeleteAll(). Multi-key calls have no key-count limit. - Values use V8 serialization, so cycles, maps, sets, and typed arrays keep their shape. Each read returns a new copy.
- Keys sort by their UTF-8 bytes.
list()supportsstart,startAfter,end,prefix,reverse, andlimit. deleteAll()removes every user table, view, and trigger, and the stored alarm.noCacheandallowConcurrencyhave no effect.allowUnconfirmed: truekeeps a write from holding the output gate.
Transactions and gates
- Writes in one JavaScript turn commit together, as in workerd.
transactionSync()runs its closure in a savepoint. A thrown error rolls back the closure’s writes and is thrown again.transaction()keeps one transaction open acrossawait. New events wait until it ends.- Input gate: while
blockConcurrencyWhile()ortransaction()runs, new fetch, RPC, alarm, and WebSocket events wait. - Output gate: a response, a
fetch(), an RPC call, or a WebSocketsend()waits until the writes made before it are durable. If a commit fails, the held output is never sent, and the object resets. blockConcurrencyWhile()times out after 30 seconds. A rejection or a timeout resets the object.ctx.storage.sync()resolves when Rivet confirms every earlier write.
Reserved tables
Orange keeps its own tables in each object’s database:
_cf_KV,_cf_ALARM, and_cf_METADATA, as workerd does._rivet_tables for RivetKit and Orange.
They show in sqlite_master, and SQL that reads or changes them fails with
not authorized. A tool that dumps every table fails on them. Do not name your
own tables with these prefixes.
Alarms
alarm()getsscheduledTime,retryCount, andisRetry.- Only one
alarm()runs at a time for an object. - When
alarm()throws, Orange retries up to 6 times, after 2, 4, 8, 16, 32, and 64 seconds, plus up to 25% jitter. AsetAlarm()ordeleteAlarm()during the handler replaces the retry. getAlarm()returnsnullwhile the alarm runs, unless the handler set a new one.- After construction,
setAlarm()rejects a class with noalarm()method.
RPC and fetch
- Calls from one Worker to one object arrive in the order you make them.
- An error that your method or
fetch()throws rejects only that call. The stub stays usable. - When the object resets, for example after
ctx.abort(), the stub breaks. Its pending and later calls reject, and the error hasdurableObjectReset: true. Callget()orgetByName()again for a new stub. - A response with
Content-Encoding: gziporbris compressed unless it setsencodeBody: "manual". - The object sees the request that the Worker sent, including
OPTIONSrequests andrequest.cf. - A pipelined call waits for its parent result, which adds round trips.
- A Durable Object stub cannot be sent over RPC. Send the ID string.
WebSockets
new WebSocketPair(),accept(), and a status101response work as on Cloudflare.ctx.acceptWebSocket(), tags,getWebSockets(),getTags(),serializeAttachment(), anddeserializeAttachment()work.webSocketMessage(),webSocketClose(), andwebSocketError()get events for accepted sockets. Binary messages areArrayBuffervalues.setWebSocketAutoResponse()answers a matching text frame without building an instance or resetting the idle timer.setHibernatableWebSocketEventTimeout()accepts up to 2,147,483,647 ms (about 24.8 days), the longest Node.js timer. It cannot stop synchronous JavaScript.- Rivet’s transport limit applies to a message.
WebSocket hibernation
Orange emulates hibernation inside a running Rivet Actor, because Rivet 3 has paused Rivet WebSocket hibernation:
- A socket host in the actor owns each accepted socket and outlives the instance.
- After 10 seconds with no event, Orange drops the instance. The sockets stay open.
- The next message, close, or error builds a new instance. Before the constructor runs, Orange restores each socket with its tags, attachment, and automatic-response timestamp. Events that arrive during construction wait and keep their order.
These differences from Cloudflare come from running hibernation without Rivet WebSocket hibernation. Orange cannot remove them.
A connected object is always a live actor
A hibernated object frees its instance, but its Rivet Actor, its sockets, and their state stay in memory. Cost grows with the number of objects that have an open socket, not with the number of objects that run code.
Measured on the packaged CLI, with one socket for each object and every object hibernated:
| Connected objects | JavaScript heap for each | Runtime process memory for each | Engine process memory for each |
|---|---|---|---|
| 1,000 | 45 KB | 420 KB | 610 KB |
| 10,000 | 44 KB | 299 KB | 431 KB |
For where the runtime’s memory goes, see the implementation notes.
One runner holds at most 4,000 awake objects
The Rivet Engine setting pegboard.sqlite_sessions limits the actors with an
open SQLite database on one runner connection. Each connected object is one.
Its default is 4,000. The next object does not start: its first request waits
and then fails.
- For
orange dev, setRIVET__PEGBOARD__SQLITE_SESSIONSin the environment. Orange passes it to the Engine that it starts. With 20,000, oneorange devheld 10,001 connected objects. - For a self-hosted Engine, set
pegboard.sqlite_sessionsin the Engine’s configuration.
Runner churn closes the sockets
Rivet cannot move an actor to another runner without closing its sockets, so a connected actor cannot move.
On Cloudflare, a code update keeps the sockets of a hibernated object connected by default since deferred code updates. A forced update or a runtime update disconnects them. On Orange, each of these events closes sockets.
Measured with two orange serve runners on one Engine and 40 objects:
| Event | The client’s close | When the object answers again |
|---|---|---|
| A runner stops for a deploy, a scale-down, or a drain | 1012 Service Restart in 0.2 seconds. With many sockets, the closes spread over up to 10 seconds. | A new connection through another runner got its reply in 0.03 to 0.33 seconds. |
| A runner crashes, and the client connected through it | 1006 at once | At once when the object runs on another runner. |
| A runner crashes, and the object ran on it | 1012 Service Restart in 0.1 seconds | Only after the Engine judges the runner lost. Until then, a request to the object waits. |
| The Engine stops | 1012 Service Restart at once | After the Engine is back. |
Orange gives 1012 only when Rivet’s error says that the runner or the Engine
went away, such as ups.consumer_closed. Any other Rivet error, such as
actor.not_found or guard.rate_limit, reaches the client as Rivet sent it:
1011 and <group>.<code>#<ray id>. Find the ray ID in the Engine’s logs.
The object’s storage survived each event. A client must connect again after any close that it did not ask for. It must wait a random time before each attempt, so that the clients of a stopped runner do not all return at once.
Facets
ctx.facets runs child objects that have their own SQLite storage. Orange
supports the part that the agents SDK uses.
| API | Status |
|---|---|
get(name, callback) | Supported. class takes a class from ctx.exports or a namespace. id takes a DurableObjectId. |
RPC and fetch() on the facet stub | Supported |
abort(name, reason) | Supported |
delete(name) | Supported |
clone(src, dst) | Supported. Forks the facet’s Rivet Actor in the background. See Clone. |
- Each facet is a child Rivet Actor. Any exported class works. It needs no binding and no migration.
get()starts nothing. The first call through the stub runs the callback and starts the facet.- After
abort()ordelete(), the nextget()runs its callback again, so a new class oridtakes effect. Afterabort(), the new instance sees the old storage. delete()fails calls withFacet was deleted.The nextget()gets empty storage.- A facet without an
idgets its parent’sctx.id. - Facets nest to a depth of 4, including the root.
setAlarm()in a facet fails withFacets currently cannot set alarms.
Clone
clone(src, dst) replaces the storage of dst and its children with a copy of
src. Cloudflare copies the SQLite files in the call. Orange forks the Rivet
Actor of src, which copies its storage on write:
clone()returns at once. Calls todstfail withFacet was cloned-over.- The parent stores a clone record and a new key for
dstbefore its next output. The fork starts once they are durable. srccommits its open turn, and Rivet forks its actor to the new key.srckeeps running.- Each child of
srcis forked the same way, under the new actor. - Orange destroys the old actor of
dst. Calls tosrcanddstwait until the clone ends.
What you can rely on:
dstholds the data ofsrcas of theclone()call. Calls todstalways see the copy.- The copy is whole or absent. It survives a restart and a crash. After the
parent’s
ctx.abort(), the parent’s next facet call stores the record again and the clone runs then; a crash before that loses the clone. A clone that runs again after a crash finds its own fork and changes nothing. - The copied tree is consistent. The children that Orange forks are the ones
that the forked actor names, and calls from
srcto its children wait until each child is forked. A child thatsrcwrites on its own while the fork runs can carry those writes into the copy. - The copy is the SQLite database itself: rowids,
AUTOINCREMENTcounters, generated columns, triggers, views, FTS5 tables, and value types. clone(name, name)aborts the facet and keeps its storage. Asrcthat never ran emptiesdst. At the maximum depth,clone()does nothing.
Forks need a Rivet Engine that speaks envoy protocol 9, such as Engine 3.1.
The Engine of orange dev and new Rivet Cloud clusters can fork. When the
Engine refuses a fork, Orange copies rows instead and logs
[durable-object] facet clone copies rows instead of forking: actor.<code>:
| Code | When |
|---|---|
fork_too_deep | src is already 16 forks deep, for example after 16 clones of clones. The row copy starts a new chain. |
fork_unavailable | The Engine cannot fork. |
fork_failed | src never started, so it has nothing to fork. |
fork_error | Any other failure, such as a token without the fork grant, or a dst key that a row copy interrupted by a crash created. |
The row copy reads every row of src in one synchronous call, which blocks the
runtime process, and writes them to dst in one transaction. Set
ORANGE_FACET_CLONE=copy to always copy rows.
| Case | Cloudflare | Orange |
|---|---|---|
src is inside storage.transaction() | Copies the state before the transaction | Waits for the transaction, then copies |
| Copy cost | A file copy | A fork of each actor in the tree |
| Facets created before clone support | Copied | Their own rows are copied. Their children are not. |
| Infrastructure failure during the copy | Not possible | Calls to dst fail until the parent restarts and runs the clone again |
Measured cost of one clone() of a facet of 256 KiB random blobs, as fork
and as row copy on the same build. Local is orange dev on a 16-core Linux
host. Cloud is a free Rivet Cloud cluster (Engine 3.1.1, one e2-small runner).
“Longest stall” is the slowest call to another Durable Object during the clone.
| Case | Fork, local | Row copy, local | Fork, cloud |
|---|---|---|---|
| 1 MB | 56 ms, 9 ms stall | 226 ms, 120 ms stall, +99 MiB | 173 ms, 15 ms stall |
| 10 MB | 56 ms, 11 ms stall | 1.1 s, 127 ms stall, +190 MiB | 152 ms, 14 ms stall |
| 100 MB | 74 ms, 20 ms stall | 10.8 s, 191 ms stall, +196 MiB | Not measured |
| 100 MB, right after the write | 87 ms to 1.1 s | 11.0 s, 725 ms stall | Not measured |
10 MB, src asleep | 71 ms | 1.4 s, +447 MiB | Not measured |
| 1 MB with 8 children of 1 MB | 464 ms | 1.2 s, 356 ms stall | Not measured |
| 8 clones of 10 MB at once | 465 ms, 25 ms stall | 6.7 s, 706 ms stall | Not measured |
A fork adds no measurable memory.
Who can call an object
Every Orange actor is a Rivet Actor in your project’s namespace: your Durable Objects, facets, and the actors of KV, D1, R2, Cache, Rate Limiting, Queues, Cron Triggers, and Workflows.
On Cloudflare, only the Worker can reach a Durable Object. On Orange, besides
your Worker, any client with a Rivet token that has an actor_gateway grant
can call your objects. Give other clients tokens without that grant, or scope
it to specific actor IDs.
- The Rivet gateway checks every call with the caller’s Rivet token and its grants. Orange adds no check of its own.
- A caller with an
actor_gatewaygrant can also set the request that an object’sfetch()sees, includingrequest.cf. orange devandorange servedrop everyx-open-orange-internal-*header that a client sends to the Worker.- The Rivet token never reaches your object’s
fetch(), WebSocket, or RPC code. - Local development is not a security boundary. The local Engine’s admin
token is
default, and any process on the machine can use it.
Debug an object
- Run
orange dev. The binding table shows each Durable Object binding asRivet Actor · <ClassName>. - To see RivetKit’s own logs, run
orange dev --log-level debug. By default,orange devshows only RivetKit errors. - Find the actor of an object. Its name is the class in kebab case and a short
hash, for example
greeter-5c8cd02c. Its key is the object’s ID.
| Symptom | Cause | Fix |
|---|---|---|
| A field of your class is empty | The instance was dropped or the actor slept | Keep the value in ctx.storage. |
| An object never hibernates or sleeps | A timer, an outbound WebSocket, a fetch(), or other work still holds it | See Find what keeps an object awake. |
| A request to a new object waits, then fails | The runner already holds 4,000 awake objects | Raise the limit. See One runner holds at most 4,000 awake objects. |
A client’s WebSocket closes with 1012 | A runner or the Engine went away | Connect again after a random wait. See Runner churn closes the sockets. |
A client’s WebSocket closes with 1011 and <group>.<code>#<ray id> | Rivet returned an error | Find the ray ID in the Engine’s logs. |
Calls reject with durableObjectReset: true | The object reset, for example after ctx.abort() or a failed commit | Call get() or getByName() again. |
RangeError that names 128 MiB | One write changed too many pages | Split the write. |
RangeError that names 32 MiB | One RPC call is too large | Send the data with stub.fetch(). |
SQL fails with not authorized | The SQL reads or changes a _cf_ or _rivet_ table | Rename your table, and skip these tables in a dump. |
Synchronous storage cannot run while another event's storage.transaction() is open | An event that was already running used sync storage during another event’s transaction() | Use the async storage API in that code path. |
A fetch() response body is cut short | The response reuses the unread request body | Read the request body before you build the response. |
Under orange dev, local Engine state is in .open-orange/rivetkit/ in your
project. The Engine’s log gets half of the free disk there, from 256 MiB to 4 GiB, and
orange dev stops with an error when less than 512 MiB is free. Set
RIVET__STORAGE__LOG_SHARD__MAX_DISK_BYTES in the shell to pick the size yourself.
orange doctor reports the free space in its disk check, with the same rule: it counts
the free disk and the log of the Worker’s own storage directory.
Deviations
These add to the reserved tables and the shorter idle timeout.
- Orange blocks
_cf_and_rivet_names with a text check, not a SQLite authorizer. There is no SQL function or PRAGMA allow-list.DELETEandUPDATEwithLIMITfail. ctx.storage.kv.list()reads the matching rows when you call it, so later writes do not appear in the iterator.- The input gate holds only new events. An event that was already running can continue during another event’s critical section.
- The output gate does not hold body chunks streamed after the headers,
outbound
new WebSocket()setup, or output from callbacks that run outside the object’s async context. - The alarm row commits before Orange updates the Rivet schedule. Startup repairs a schedule that a crash left missing or stale.
ctx.abort()and broken storage restart the complete Rivet actor. About 1 call in 600 that overlapsctx.abort()fails with503.- An object that closes a standard WebSocket itself stays awake.
- A client’s close code can be lost in the Rivet gateway. In the recorded
lifecycle probe, a clean
1000close reachedwebSocketClose()as1001. - A stub has no request owner, so a stub kept in a global works in later requests.
- Classes from
new_classessupportctx.storage.sql, where Cloudflare throws. - In a new parent instance, the first
get()of a facet applies its callback’s class even when the facet actor is still awake. - A facet whose stored class is no longer exported cannot start. Call
delete(). - A parent’s
ctx.abort()andstorage.deleteAll()do not reach its facets.ctx.facets.abort()restarts only the named facet. - Each facet call goes through the Rivet gateway. A class change restarts the facet actor.
delete()destroys the old facet actor in the background. If that fails, the actor stays. Facets nested in a deleted facet are not destroyed.- A facet stub cannot be sent over RPC.
Not supported
- Container images other than Cloudflare Sandbox images.
- Per-request
ctx.propsvalues. - Point-in-time recovery with
getBookmarkForTime()andonNextSessionRestoreBookmark(). - Snapshots with
snapshot()andonNextSessionRestore(). - Read replicas with
ensureReplicas()anddisableReplicas(). ctx.restore()andctx.configureReadReplication().stub.connect()and theconnect()handler.- Bindings to another Worker with
environmentornamespace_id. - Moving existing objects with a
transferred_classesmigration. - Durable Object
exportsconfiguration.
Their types stay in the generated contract, and each placeholder throws an error that says it is not supported.
Conformance
tests/durable-objects/durable-object-facets.test.tsandtests/durable-objects/durable-object-facet-clone.test.tsrun facets and workerd’s facet clone test on a realorange dev.tests/rpc-and-websockets/accepted-websockets.test.tsruns hibernation, the work that keeps an object awake, and theheldline onorange devwith a real Rivet Engine.- The conformance package runs workerd’s upstream tests against
orange devand ports workerd’s C++ Durable Object tests for alarms, IDs, the input gate, SQL, storage, and WebSockets. - Generated type checks compare Orange’s Durable Object types with the pinned Wrangler declarations.
The implementation notes list every test suite.
Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.
Durable Objects
| Check | Status | Results |
|---|---|---|
| Storage API: get, put, list, delete, transaction, sync KV | Works |
|
KV-backed classes (new_classes) | Works |
|
| Object ids and input gates | Works |
|
| Alarms | Works |
|
| An alarm due while the process is down | Works |
|
| RPC and entrypoints | Partial |
|
| WebSockets through an object | Works |
|
| WebSocket hibernation | Partial |
|
Durable Object Facets
| Check | Status | Results |
|---|---|---|
| Durable Object facets | Works |
|