workerd error: concurrent open connections limit hit on durable object

TL;DR: Spread the connections across more Durable Object instances. Each instance caps concurrent open connections, so shard clients over many object IDs (for example by room, user, or hash), close idle websockets promptly, and use the hibernation API so idle sockets cost nothing. One object per chat room does not scale to one object for the whole app.

workerd error: concurrent open connections limit hit on durable object

1. Confirm the bottleneck is per-instance. Log which object ID each failing connection targets and count concurrent connections per ID.

Expected: failures cluster on a few hot object IDs while quiet ones are fine.

1. Shard the namespace. Derive the object ID from something with natural fan-out, like a room ID, document ID, or a hash of the user ID, instead of routing everyone to one object:

   const id = env.ROOMS.idFromName(roomId);
   const stub = env.ROOMS.get(id);

Expected: connections spread across many instances, each well under the cap.

1. Close idle connections. Add an idle timeout on the websocket and close it server-side when the client goes quiet.

Expected: connection count per instance tracks active users, not everyone who ever connected.

1. Use the hibernation API for websocket handlers so idle sockets do not hold the object awake burning resources.

Expected: idle connections survive without counting against active work, and the object can evict cleanly.

1. If one logical entity still needs more connections than a single instance allows, shard that entity too, for example by splitting a giant room into numbered shards.

Expected: no single instance ever approaches the cap.

1. Load-test with realistic concurrent connection counts per shard key.

Expected: tail shows no connection-limit errors at peak.

Use this when

• websockets to a Durable Object fail as concurrent users grow
• one object ID serves a whole feature (one global chat room, one presence object)
• connections work for the first N users then start failing
• you need many long-lived connections per logical entity

Not for this skill when

• the error is about Durable Object storage size rather than connections
• connections fail immediately even with one client (that is a handshake or routing bug)
• the limit being hit is the worker subrequest cap, not the per-object connection cap
• you need broadcast to millions (that is a fan-out architecture problem, consider sharding plus pub/sub)

Variant phrasings

• Durable Object too many connections
• "concurrent open connections limit" durable object
• websocket limit per durable object instance
• DO connection limit hit
• Cloudflare Durable Object max connections

Why it happens

A Durable Object instance is a single-threaded isolate with a cap on concurrent open connections. Routing every client to one ID concentrates all connections onto one isolate, so growth hits the cap linearly. Sharding turns one hot isolate into many cool ones, each with its own connection budget, which is the only way the total can scale.

Edge cases

• Hibernation changes handler semantics. Test reconnect and message ordering carefully after switching.
• Sharding by user hash breaks cross-user broadcast unless you add a coordination layer. Shard by the broadcast domain (the room), not the user, when everyone must hear everyone.
• Idle timeouts that are too aggressive cause reconnect storms. Tune the timeout to real usage patterns.
• Object IDs derived from names are deterministic. That is what makes sharding work, but it also means a hot shard key stays hot. Pick keys with real fan-out.
• Migrations and alarms run per instance. Sharding multiplies them, so keep per-instance alarm and storage usage small.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_V5z9WWRzXmQCnzJo51T6Aw