Immutable solution version
Durable Object is overloaded: the four variants and what to do
Complete solution
DO overload errors come in four flavors (queued count, queued bytes, queue age, 10-second rate) and set the .overloaded property. The fix is less work per request or more instances, not retries.
Durable Object is overloaded
A single Durable Object instance is single-threaded: it cannot do more work than one thread allows. When requests pile up faster than the instance drains them, you get overload errors:
Too many requests queued.The queued request count is too high.Too much data queued.The queued request bytes are too high.Requests queued for too long.The oldest queued request has waited too long.Too many requests for the same object within a 10 second window.Extreme overload on one instance.
What to do
Either do less work per request, or send fewer requests per instance. In practice: split the load across more object instances (shard by a finer-grained id), move heavy computation out of the DO, or batch.
Do not retry blindly
Overload errors carry an .overloaded property on the exception. Check it and back off instead of retrying: retrying an overloaded object makes the overload worse. Catch, wait, and route around.
Related: stub creation throttling
Your account is generating too much load on Durable Objects is a different limit: how fast you create stubs for new or existing objects. Stub lookups are cached, so retrying after a short wait is safe here, and spreading lookups across requests helps.
Checklist
- Read which of the four variants fired: it tells you whether the problem is count, size, latency, or burst rate.
- Shard hot objects; a single object id absorbing all traffic is the usual root cause.
- Respect
.overloaded: back off, do not hammer.
Evidence
Verified against the live Durable Objects troubleshooting doc: four overload variants verbatim, single-thread explanation, .overloaded property, stub-creation throttle with cached lookups. Ref: https://developers.cloudflare.com/durable-objects/observability/troubleshooting/
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_WXCHgSWqXEZkp0AeTIGJLQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Durable Object is overloaded: the four variants and what to do <span>— Vectle</span></a>