Skip to content
Storage / Durable Objects

Storage

Durable Objects

Run Cloudflare Durable Objects on OpenOrange, where each object is one Rivet Actor with its own SQLite database.

Partial

Runs on Rivet Actors with SQLite storage and alarms

Works
SQL and key-value storage, transactions, alarms, RPC, fetch(), and WebSockets, through the same cloudflare:workers API
Differs
An idle object loses its instance fields after 10 seconds
Missing
stub.connect(), point-in-time recovery, read replication, and ctx.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

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.

  1. 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"] }]
    }
  2. Write the class

    Extend DurableObject and 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 };
      }
    }
  3. 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>;
  4. Run it

    orange dev shows 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:8787

    Each 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.storage reads 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

FeatureStatusNotes
idFromName(), newUniqueId(), idFromString(), get(), getByName(), jurisdiction()SupportedLocation hints and jurisdictions are checked, but they do not change where an object runs.
Method RPC on a stubSupportedStreams, RpcTarget, callbacks, and pipelined calls work. A class that does not extend DurableObject gets fetch() and alarms, but no RPC.
stub.fetch()SupportedRequest and response bodies stream.
stub.connect()Not supportedThrows. Service binding connect() works.
ctx.storage.sqlSupportedA cursor reads all its rows before it returns.
ctx.storage.kv and the async storage APISupported
transactionSync() and transaction()Supported
AlarmsSupported
getCurrentBookmark(), waitForBookmark()SupportedBookmarks use the local workerd format.
getBookmarkForTime(), onNextSessionRestoreBookmark()Not supportedReading one throws a NotSupportedError.
snapshot(), onNextSessionRestore()Not supportedReading one throws a NotSupportedError.
ensureReplicas(), disableReplicas()Not supportedReading one throws a NotSupportedError.
blockConcurrencyWhile(), waitUntil(), abort()Supportedabort() restarts the whole Rivet Actor.
ctx.exportsSupported
Standard WebSocketsSupported
WebSocket hibernation APIPartialEmulated. See WebSocket hibernation.
ctx.facetsPartialget(), abort(), delete(), and clone(): the part that the agents SDK uses. See Facets.
ctx.containerPartialRuns only Cloudflare Sandbox images. See Sandbox.
ctx.props, ctx.restore, ctx.configureReadReplication, ctx.primaryStub, ctx.versionNot supportedReading 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:

WhatLimitWhat happens over it
One storage write128 MiB of changed SQLite pages in one commitThe write throws a RangeError that names the limit.
One RPC call32 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 secondsThe object resets.
Idle time before the instance or actor stops10 secondsSee Lifecycle.
Alarm retries6The alarm is dropped.
Facet depth4, including the rootclone() does nothing at the maximum depth.
Awake objects on one runner4,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 objectNo 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.jsoncOn Orange
new_sqlite_classesCreates the class, with SQLite storage.
new_classesThe same. Orange stores every class in SQLite, so these classes can use SQL too.
renamed_classesThe class keeps its objects.
deleted_classesThe class goes away. Its objects’ data stays in storage.
transferred_classesThe class starts empty. Orange does not move the objects that the other Worker stored.
Any other migration fieldorange dev stops with an error.
A binding with script_nameWorks when that Worker runs in the same orange dev session. See Multiple Workers.
A binding with environment or namespace_idLoads 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.exports or the exports import from cloudflare:workers.
  • A bound class with no migration that creates it stops orange dev with an error.
  • RPC to a plain class that does not extend DurableObject fails, also with the js_rpc flag, 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() or ctx.keepAwake() task.
  • A pending setTimeout() or setInterval() callback, until it runs or you clear it. unref() does not change that. The timers of node:timers and node:timers/promises are 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):1

The held line means that no event of the object started or ended for the idle timeout, and the object still runs.

  • idle_ms is the time since the last event started or ended. For a handler that still runs, it is how long the handler has run.
  • held_by names each cause with its count.
CauseWhat holds the object
timerA pending setTimeout() or setInterval() callback. timers lists each kind with its delay and count.
standard-websocketAn open WebSocket that the object accepted with accept().
outbound-websocketAn open WebSocket that the object opened, with new WebSocket() or through a Durable Object stub.
fetchA fetch() whose response has not arrived.
wait-untilA ctx.waitUntil() promise that has not settled.
eventA request, message, or alarm handler that still runs.
rpc-sessionAn open RPC session with a caller.
rpc-resultAn RPC result that a caller has not collected. It expires after 30 seconds.
unclaimed-upgradeA WebSocket upgrade whose client has not connected. It expires after 30 seconds.
keep-awakeWork 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 every held line, for as long as the object runs, as held_by=timer:1 timers=setInterval(3000ms):1.
  • Only for an object that has a WebSocket. An object with no WebSocket prints no held line, 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 support next(), 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.
  • databaseSize uses workerd’s formula: allocated pages minus free pages, times the page size.
  • The cursor reads all rows before it returns. rowsRead counts returned rows, not scanned rows. rowsWritten counts the changes of one INSERT, UPDATE, DELETE, or REPLACE, 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, and RELEASE through exec() fail. Use transactionSync() or transaction().
Key-value storage
  • ctx.storage.kv has synchronous get(), put(), delete(), and list() on the same database and transaction as SQL.
  • The async API has get(), put(), delete(), list(), and deleteAll(). 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() supports start, startAfter, end, prefix, reverse, and limit.
  • deleteAll() removes every user table, view, and trigger, and the stored alarm.
  • noCache and allowConcurrency have no effect. allowUnconfirmed: true keeps 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 across await. New events wait until it ends.
  • Input gate: while blockConcurrencyWhile() or transaction() runs, new fetch, RPC, alarm, and WebSocket events wait.
  • Output gate: a response, a fetch(), an RPC call, or a WebSocket send() 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() gets scheduledTime, retryCount, and isRetry.
  • 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. A setAlarm() or deleteAlarm() during the handler replaces the retry.
  • getAlarm() returns null while the alarm runs, unless the handler set a new one.
  • After construction, setAlarm() rejects a class with no alarm() 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 has durableObjectReset: true. Call get() or getByName() again for a new stub.
  • A response with Content-Encoding: gzip or br is compressed unless it sets encodeBody: "manual".
  • The object sees the request that the Worker sent, including OPTIONS requests and request.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 status 101 response work as on Cloudflare.
  • ctx.acceptWebSocket(), tags, getWebSockets(), getTags(), serializeAttachment(), and deserializeAttachment() work.
  • webSocketMessage(), webSocketClose(), and webSocketError() get events for accepted sockets. Binary messages are ArrayBuffer values.
  • 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 objectsJavaScript heap for eachRuntime process memory for eachEngine process memory for each
1,00045 KB420 KB610 KB
10,00044 KB299 KB431 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, set RIVET__PEGBOARD__SQLITE_SESSIONS in the environment. Orange passes it to the Engine that it starts. With 20,000, one orange dev held 10,001 connected objects.
  • For a self-hosted Engine, set pegboard.sqlite_sessions in 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:

EventThe client’s closeWhen the object answers again
A runner stops for a deploy, a scale-down, or a drain1012 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 it1006 at onceAt once when the object runs on another runner.
A runner crashes, and the object ran on it1012 Service Restart in 0.1 secondsOnly after the Engine judges the runner lost. Until then, a request to the object waits.
The Engine stops1012 Service Restart at onceAfter 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.

APIStatus
get(name, callback)Supported. class takes a class from ctx.exports or a namespace. id takes a DurableObjectId.
RPC and fetch() on the facet stubSupported
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() or delete(), the next get() runs its callback again, so a new class or id takes effect. After abort(), the new instance sees the old storage.
  • delete() fails calls with Facet was deleted. The next get() gets empty storage.
  • A facet without an id gets its parent’s ctx.id.
  • Facets nest to a depth of 4, including the root.
  • setAlarm() in a facet fails with Facets 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:

  1. clone() returns at once. Calls to dst fail with Facet was cloned-over.
  2. The parent stores a clone record and a new key for dst before its next output. The fork starts once they are durable.
  3. src commits its open turn, and Rivet forks its actor to the new key. src keeps running.
  4. Each child of src is forked the same way, under the new actor.
  5. Orange destroys the old actor of dst. Calls to src and dst wait until the clone ends.

What you can rely on:

  • dst holds the data of src as of the clone() call. Calls to dst always 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 src to its children wait until each child is forked. A child that src writes on its own while the fork runs can carry those writes into the copy.
  • The copy is the SQLite database itself: rowids, AUTOINCREMENT counters, generated columns, triggers, views, FTS5 tables, and value types.
  • clone(name, name) aborts the facet and keeps its storage. A src that never ran empties dst. 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>:

CodeWhen
fork_too_deepsrc is already 16 forks deep, for example after 16 clones of clones. The row copy starts a new chain.
fork_unavailableThe Engine cannot fork.
fork_failedsrc never started, so it has nothing to fork.
fork_errorAny 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.

CaseCloudflareOrange
src is inside storage.transaction()Copies the state before the transactionWaits for the transaction, then copies
Copy costA file copyA fork of each actor in the tree
Facets created before clone supportCopiedTheir own rows are copied. Their children are not.
Infrastructure failure during the copyNot possibleCalls 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.

CaseFork, localRow copy, localFork, cloud
1 MB56 ms, 9 ms stall226 ms, 120 ms stall, +99 MiB173 ms, 15 ms stall
10 MB56 ms, 11 ms stall1.1 s, 127 ms stall, +190 MiB152 ms, 14 ms stall
100 MB74 ms, 20 ms stall10.8 s, 191 ms stall, +196 MiBNot measured
100 MB, right after the write87 ms to 1.1 s11.0 s, 725 ms stallNot measured
10 MB, src asleep71 ms1.4 s, +447 MiBNot measured
1 MB with 8 children of 1 MB464 ms1.2 s, 356 ms stallNot measured
8 clones of 10 MB at once465 ms, 25 ms stall6.7 s, 706 ms stallNot 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_gateway grant can also set the request that an object’s fetch() sees, including request.cf.
  • orange dev and orange serve drop every x-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

  1. Run orange dev. The binding table shows each Durable Object binding as Rivet Actor · <ClassName>.
  2. To see RivetKit’s own logs, run orange dev --log-level debug. By default, orange dev shows only RivetKit errors.
  3. 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.
SymptomCauseFix
A field of your class is emptyThe instance was dropped or the actor sleptKeep the value in ctx.storage.
An object never hibernates or sleepsA timer, an outbound WebSocket, a fetch(), or other work still holds itSee Find what keeps an object awake.
A request to a new object waits, then failsThe runner already holds 4,000 awake objectsRaise the limit. See One runner holds at most 4,000 awake objects.
A client’s WebSocket closes with 1012A runner or the Engine went awayConnect 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 errorFind the ray ID in the Engine’s logs.
Calls reject with durableObjectReset: trueThe object reset, for example after ctx.abort() or a failed commitCall get() or getByName() again.
RangeError that names 128 MiBOne write changed too many pagesSplit the write.
RangeError that names 32 MiBOne RPC call is too largeSend the data with stub.fetch().
SQL fails with not authorizedThe SQL reads or changes a _cf_ or _rivet_ tableRename your table, and skip these tables in a dump.
Synchronous storage cannot run while another event's storage.transaction() is openAn 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 shortThe response reuses the unread request bodyRead 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. DELETE and UPDATE with LIMIT fail.
  • 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 overlaps ctx.abort() fails with 503.
  • 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 1000 close reached webSocketClose() as 1001.
  • A stub has no request owner, so a stub kept in a global works in later requests.
  • Classes from new_classes support ctx.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() and storage.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.props values.
  • Point-in-time recovery with getBookmarkForTime() and onNextSessionRestoreBookmark().
  • Snapshots with snapshot() and onNextSessionRestore().
  • Read replicas with ensureReplicas() and disableReplicas().
  • ctx.restore() and ctx.configureReadReplication().
  • stub.connect() and the connect() handler.
  • Bindings to another Worker with environment or namespace_id.
  • Moving existing objects with a transferred_classes migration.
  • Durable Object exports configuration.

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.ts and tests/durable-objects/durable-object-facet-clone.test.ts run facets and workerd’s facet clone test on a real orange dev.
  • tests/rpc-and-websockets/accepted-websockets.test.ts runs hibernation, the work that keeps an object awake, and the held line on orange dev with a real Rivet Engine.
  • The conformance package runs workerd’s upstream tests against orange dev and 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
  • Pass 24/24: synthetic--do-storage-test
  • Pass 1/1: api-tests--actor-kv-test
  • Pass 1/1: api-tests--sync-kv-test
  • Pass: lifecycle: storage: a value survives the object's sleep
KV-backed classes (new_classes) Works
  • Pass: lifecycle: KV-backed class: the storage API keeps a value
  • Pass: lifecycle: KV-backed class: SQL is available
Object ids and input gates Works
  • Pass 2/2: synthetic--do-id-test
  • Pass 5/5: synthetic--do-input-gate-test
  • Not run: api-tests--actor-block-concurrency-depth-test
Alarms Works
  • Pass 17/17: synthetic--do-alarm-test
  • Pass: lifecycle: alarm: fires on time
  • Pass: lifecycle: alarm: wakes a sleeping object with no request
  • Pass: lifecycle: alarm: a future alarm survives a restart
An alarm due while the process is down Works
  • Pass: lifecycle: alarm: an alarm due while the process is down fires after a restart, with no request
RPC and entrypoints Partial
  • Partial 154/179: workerd tests: RPC + entrypoints
  • Pass: api-tests--request-signal-enabled > abortIfClientAbandonsRequest
  • Pass: api-tests--request-signal-enabled > abortedRequestDoesNotAbortSubrequest
WebSockets through an object Works
  • Pass 11/11: synthetic--do-websocket-test
  • Pass: workers-chat-demo: two clients chat in a room, and history is kept
WebSocket hibernation Partial
  • Partial 2/3: synthetic--do-websocket-hibernation-test
  • Fail: lifecycle: hibernation: a socket stays open through the object's sleep, and a message wakes it
  • Pass: lifecycle: open socket: an idle socket stays open past the sleep timeout
  • Pass: lifecycle: open socket: an idle object drops its in-memory state while its socket stays open
  • Pass: lifecycle: open socket: the object sleeps after its last socket closes
  • Fail: lifecycle: open socket: webSocketClose gets the client's close code
  • Pass: lifecycle: open socket: a restart closes it with 1012, and a reconnect finds storage
  • Pass: lifecycle: open socket: a crash closes it with 1006, and a reconnect finds storage
  • Pass: cluster-websocket: an idle socket on a pool URL, with no pings, closes at 125 s with 1006
  • Pass: cluster-websocket: with pings, idle sockets stay open until a rollout closes them at 695 s
  • Pass: cluster-websocket: a rollout closes sockets with 1012, and each client reconnects on the first try
  • Pass: cluster-websocket: a socket can also close with 1011 when its object's generation ends
  • Pass: cluster-websocket: after a rollout the object is a new instance, and an accepted socket's storage is kept
  • Pass: cluster-websocket: a cut client gives the object webSocketClose 1006 within about 1 s, and the object sleeps
  • Pass: cluster-websocket: a client that stops answering pings is closed with 1006 at about 90 s, and the object sleeps
  • Pass: cluster-websocket: wrangler dev keeps idle sockets open for 360 s with no pings
  • Pass: keep-awake-memory: 1,000 objects with one idle socket each cost about 1.1 MB per object
  • Pass: keep-awake-memory: 1,000 idle sockets on one object cost about 0.2 MB per socket after a long hold
  • Pass: keep-awake-memory: about half of an object's cost stays after it sleeps
Durable Object Facets
Check Status Results
Durable Object facets Works
  • Pass: example: facets-loader