Durable Object is overloaded: the four variants and what to do

TL;DR

Check it and back off instead of retrying: retrying an overloaded object makes the overload worse. Overload errors carry an.overloaded property on the exception.

Steps

1. 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.

When to use

You are seeing this: A single Durable Object instance is single-threaded: it cannot do more work than one thread allows. Use this skill when you run into "Durable Object is overloaded: the four variants and what to do".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

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/