skip to content

A Cloudflare Durable Object reached via idFromName("global") counts every document's views and now throws 'Durable Object is overloaded'; why, and how do you fix it?

level: seniorimportance: should knowfreq 52%

answer

  1. one name, one instance, one thread
  2. about 1,000 requests per second
  3. e.overloaded means do not retry
  4. spread over many names
  5. sum the shards on read

basics

~20 s

One name maps to one single-threaded object, with a soft limit of about 1,000 requests per second; past that its queue fills and calls fail as overloaded. Shard the counter over many named objects, or per document, and sum on read.

solid answer

~40 s

`idFromName("global")` sends every view in the application to one instance, and one instance runs on one thread. Cloudflare documents a soft limit of about 1,000 requests per second per object, lower when each request does more work. Beyond that, requests queue, and when the queue grows too long or too old the caller gets errors such as `Durable Object is overloaded. Too many requests queued.` with `.overloaded` set, which you must not retry because retries add load. The fix is to stop funnelling: count per document with `getByName(docId)` where the natural unit allows, or shard a truly global total over N names (`views-0` to `views-15`), pick one per write at random, and fan out reads with `Promise.all()` to sum them. Size N from peak rate divided by per-object capacity, with headroom.

code

javascript · 27 lines
javascript
import { DurableObject } from "cloudflare:workers";

const SHARDS = 16;

export class ViewCounterShard extends DurableObject {
  async increment() {
    const n = (await this.ctx.storage.get("n")) ?? 0;
    await this.ctx.storage.put("n", n + 1);
  }
  async count() {
    return (await this.ctx.storage.get("n")) ?? 0;
  }
}

export default {
  async fetch(request, env) {
    if (request.method === "POST") {
      const shard = Math.floor(Math.random() * SHARDS);
      await env.VIEWS.getByName(`views-${shard}`).increment();
      return new Response(null, { status: 204 });
    }
    const counts = await Promise.all(
      Array.from({ length: SHARDS }, (_, i) => env.VIEWS.getByName(`views-${i}`).count())
    );
    return Response.json({ total: counts.reduce((a, b) => a + b, 0) });
  },
};

go deeper

for a junior

Recall that one name means one object on one thread, so a single global object becomes a bottleneck.

for a middle

Explain the roughly 1,000 requests per second soft limit, what an overloaded error looks like, and why e.overloaded is not retried.

for a senior

Diagnose the hot object, then shard by a natural key or N deterministic names, size N from peak load, and plan the read fan-out.

for a principal

Weigh exact real-time aggregates against approximate rolled-up ones, since exactness is what forces a single coordination point.

## Why one object saturates A **Durable Object** ID addresses exactly one instance worldwide, and that instance executes JavaScript on a single thread. `env.COUNTER.idFromName("global")` is therefore a design decision: *all* traffic for that name lands on one thread in one location. That is ideal for coordination (one place where state changes) and fatal for a high-volume aggregate such as page views across every document. Cloudflare's documented figures: - An individual object has a **soft limit of about 1,000 requests per second**. - Heavier work per request lowers that: roughly 500 to 750 per second with JSON parsing and validation, 200 to 500 with storage writes and transformation. - The number of objects per namespace is **unlimited**, so the platform scales by adding objects, never by making one object faster. ## What the overload looks like When requests arrive faster than the object drains them, they queue. When the queue is too long, too large or too old, callers receive errors such as: | Error text | Meaning | |---|---| | `Durable Object is overloaded. Too many requests queued.` | queued request count too high | | `Durable Object is overloaded. Too much data queued.` | queued payload size too high | | `Durable Object is overloaded. Requests queued for too long.` | the oldest request waited too long | | `... Too many requests for the same object within a 10 second window.` | a more extreme burst | These exceptions carry **`.overloaded`** set to `true`. The guidance is explicit: **do not retry** them, because retries add load to the object that is already behind. Errors with **`.retryable`** set are a different class (transient infrastructure failures) and can be retried with exponential backoff, on a fresh stub, when the operation is idempotent. ## Sharding the hot key The fix is to divide the work across many object names. Two patterns cover most cases: 1. **Use the natural unit.** If the counter really is per document, address it per document: `env.VIEWS.getByName(docId)`. Each document's views land on its own object, and load spreads in proportion to how many documents are being read. 2. **Shard a global aggregate.** If you genuinely need one global total, split it into N sub-counters with deterministic names: - On write, pick a shard (`views-${Math.floor(Math.random() * N)}`, or a hash of the request) and increment it. - On read, call all N shards in parallel with `Promise.all()` and sum. - Choose N from **peak requests per second divided by per-object capacity**, then add headroom; at 8,000 views per second and a few hundred writes per second per object, that means dozens of shards, not two. Trade-offs to say out loud: - **Reads get more expensive** as N grows, because each total is an N-way fan-out. If reads are frequent, have a separate object or a scheduled job roll the shards up periodically and serve the cached total. - **Exact real-time totals cost more** than approximate ones; a dashboard rarely needs per-request accuracy. - **Do not batch in memory** inside one hot object to dodge the limit: buffered increments are lost if the object is evicted, and the single thread still receives every request. - **Changing N later** changes which names hold counts; keep reading the old shard names until their values are folded in. ## Related limits worth knowing - Creating stubs to very many new or rarely used objects in a burst can hit an account-level lookup limit, surfaced as `Your account is generating too much load on Durable Objects. Please back off and try again later.` That one is safe to retry after a short wait. - `locationHint` and `jurisdiction` choose *where* an object runs; neither adds capacity. A single object stays a single thread wherever it is placed. The general idea of splitting a hot key is shared by every partitioned system and covered with database sharding; the Cloudflare-specific part is that the shard is just another name passed to `idFromName()`, objects are free to create, and the overload signal arrives as an exception with `.overloaded` that your Worker must treat as non-retryable.

  • Your Worker catches an error from the counter stub with e.retryable true. How does that differ from e.overloaded?
    retryable marks a transient infrastructure failure: retry with exponential backoff, on a new stub, if the operation is idempotent. overloaded means the object is already behind; retrying deepens the queue and raises the error rate, so shed or spread the load instead. An increment is not idempotent, so even a retryable failure needs care.
  • Would a locationHint near most readers relieve the overloaded counter?
    No. A hint only picks where a new object is created; the object is still one thread with the same per-object capacity. It can cut latency for nearby callers but adds no throughput. Only more objects, through sharding or a finer natural unit, add capacity.
  • How do you pick the number of shards?
    Divide peak requests per second by what one object sustains for that work, which is lower than 1,000 when each call writes storage, then add headroom for bursts. Weigh it against read cost, since every total is an N-way fan-out, and plan how to fold old shards in if N changes.

One ticket window serving a whole stadium: the clerk is not slow, there is just one of them. Opening more windows labelled 1 to 16 and adding up their sales at closing time is sharding; shouting the same order again at the first window is retrying an overloaded call.

  • Retrying overloaded Durable Object errors with backoff will clear them
  • Durable Objects scale vertically, so a busy object gets more threads
  • A locationHint or jurisdiction adds capacity to a hot object
  • Buffering counts in memory in the hot object safely avoids the limit
  • The number of Durable Objects per namespace is tightly limited