Cloudflare Workers Error 1101: When Counting Kills the Click

I run the click tracker for this site as a single Cloudflare Worker — 228 lines, one KV namespace, no framework. It counts pageviews and forwards affiliate clicks through /go/<id> redirects. On July 30, while verifying the bot filter I had shipped the day before, I found a bug that had never fired but was waiting to: on the day my KV writes hit a limit, the tracker would not just stop counting. It would start answering affiliate clicks with Error 1101: Worker threw exception — taking down the one route that makes money, because of a counter nobody needs in real time.

This post is the anatomy of that bug: what error 1101 actually means, the exact chain that produces it from a KV limit, and the small fix — fail-open counters plus ctx.waitUntil() — that separates the money path from the counting path.

What error 1101 actually is

Cloudflare's official page for error 1101 says it typically occurs when a Worker encounters a runtime JavaScript exception, and the recommended resolution is exactly that blunt: fix the exception in your code. On a Worker-only route there is no origin server to fall back to. If an exception escapes your fetch handler, the visitor gets a Cloudflare-branded error page, and you see nothing unless you were already watching wrangler tail or had observability switched on — both of which are off by default in one way or another.

Most 1101 write-ups stop at "check your logs for the exception." Fair. But the more useful question is the one this incident forced on me: which awaits in my handler can throw, and what do they take down with them when they do?

The failure chain, link by link

My counter was a four-line read-modify-write, and every route awaited it inline:

async function bump(env, key) {
  const cur = parseInt((await env.STATS.get(key)) || "0", 10);
  await env.STATS.put(key, String(cur + 1));
}

// in the redirect route:
await bump(env, `clicks:${today()}:${id}`);
return Response.redirect(target, 302);

Now the chain. The KV limits page gives the free plan 1,000 writes per day, and the pricing page states what happens past that: if you exceed any one of these limits, further operations of that type will fail with an error. So on a day the write budget runs out, env.STATS.put() rejects. bump() has no try/catch, so the rejection propagates. It escapes the fetch handler. The Worker returns 1101. Response.redirect(target, 302) — the line after — never runs.

Read that chain from the visitor's side: someone clicks a product link in a post, and instead of Amazon they get an error page. The counter was optional. The redirect is the entire point of the route. I had wired the optional thing so that its failure kills the mandatory thing — priority inversion in about the purest form it comes in.

To be precise about what happened and what did not: no visitor ever saw this 1101. The tracker currently does fewer than 100 writes a day against the 1,000 cap, and I found the path by re-reading bump() during bot-filter verification, not in a postmortem. But the trigger is not exotic. Writes are the first KV limit a static-site tracker exhausts, the limits page caps writes to the same key at one per second on every plan including paid, and a traffic spike concentrated on one post is exactly the event that blows a write budget — on the same day you most want the redirects up.

The fix: fail open, count later

Two changes, committed together on July 30:

async function bump(env, key) {
  try {
    const cur = parseInt((await env.STATS.get(key)) || "0", 10);
    await env.STATS.put(key, String(cur + 1));
  } catch (e) {
    console.log(`bump failed ${key}: ${e}`); // visible in wrangler tail only
  }
}

// in the redirect route:
const human = !isBot(req);
ctx.waitUntil((async () => {
  await bump(env, `clicks:${today()}:${id}`);
  if (human) await bump(env, `hclicks:${today()}:${id}`);
})());
return Response.redirect(target, 302);

• Fail open. Aggregation errors get swallowed and logged. A counter that silently undercounts on its worst day is a much smaller loss than a redirect that errors on its busiest day. The log line only surfaces in wrangler tail, which is an accepted cost — I check tail when numbers look wrong, not the other way around.
• Count after responding. The runtime docs describe ctx.waitUntil() as extending the lifetime of your Worker, allowing you to perform work without blocking returning a response. The person clicking no longer waits for two KV round trips that they get zero value from. This has been the canonical pattern for years — it was the standard HN answer back in 2021 to the complaint that Workers block the HTTP request.

The docs add two caveats worth taking seriously. Promises handed to waitUntil get 30 seconds after the invocation ends, shared across all waitUntil calls in the request, and anything unsettled gets canceled. And Cloudflare recommends Queues for out-of-band work that must not be lost. That recommendation is correct, and I am ignoring it deliberately: this counter is allowed to lose a count. It already does — KV has no atomic increment, and I measured concurrent hits collapsing into one. A number that is approximate by design should never be load-bearing; the referee for money is Amazon's report, not my KV namespace.

What I verified after deploying

Post-deploy checks, run against production, recorded in the commit message:

• A bot-flagged request produced views 1 / hviews 0 — raw and human counters split as designed.
• A human request produced views 1 / hviews 1.
• The referrer counter recorded the human source only. (The same commit closed a second hole: the 7/29 bot filter had gated views and clicks but never ref:.)
• /go/<id> still answered 302.

What I could not verify directly is the original failure firing, since triggering it would mean burning through the day's real write quota on the live tracker. The chain rests on the documented limit behavior quoted above plus the absence of any catch between put() and the handler boundary — which is exactly the class of cause the 1101 page describes.

The audit this generalizes to

The transferable lesson is not "wrap KV in try/catch." It is a two-question audit for every await inside a fetch handler:

1. Does the response depend on this operation? For my redirect route, the get(`link:${id}`) lookup does — if that fails, there is nothing useful to return anyway. The counter writes do not.
2. What exactly happens when it throws? Not "can it throw" — on a platform where quota exhaustion surfaces as a thrown error, everything can. The question is which user-visible path is downstream of it.

Anything that fails question 1 and sits inline anyway is a 1101 waiting for the day your traffic outgrows a limit you forgot you had. Move it behind waitUntil, make it fail open, and decide on purpose which failures you are willing to not see.

FAQ

What causes Cloudflare error 1101?

Error 1101 means the Worker on that route threw an uncaught runtime JavaScript exception — an unhandled promise rejection, a missing binding, or any operation that throws with no catch before the handler boundary. Cloudflare's resolution is to find the exception in your Worker logs and fix it in code; there is no origin fallback on a Worker-only route.

Does exceeding the Workers KV free tier write limit throw an error?

Yes. Cloudflare's KV pricing documentation states that once you exceed a daily free tier operation limit, further operations of that type fail with an error. Inside a Worker that surfaces as a rejected promise from put(), and if nothing catches it, the request ends in error 1101.

Is ctx.waitUntil guaranteed to complete?

No. Promises passed to ctx.waitUntil() get up to 30 seconds after the invocation ends, shared across all waitUntil calls in the request; anything unsettled is canceled. Cloudflare recommends Queues for out-of-band work that must not be lost — waitUntil is for work you can afford to drop, like this counter.

The bug, fix, and verification steps come from this repo's commit of July 30, 2026 to ops/tracker/worker.js, quoted verbatim above; post-deploy checks ran against the production tracker the same day. Limit and runtime behavior is cited from Cloudflare's error 1101, KV limits, KV pricing, and Workers context documentation, all read on August 8, 2026. The 1101 itself never reached a visitor — the failure chain is documented behavior plus the uncaught path, not an observed outage, and the body says so where it matters. Some links are affiliate links (our own product); commissions land on the public ledger.