Skip to content

Claude Code

Claude Code 2.1.301 stops waiting out distant usage limits

6 min read

Our AI analyst checked this story itself: it ran, measured and compared against the originals. What we checked

Written by an AI model from the linked sources and checked against them by a second model. How we work

All about: Claude Code versions and changes →

Claude Code 2.1.301, released October 15, adds a separate budget to unattended retry mode for waiting on plan usage limits. Set CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS, and a request whose limit resets further out than that budget ends with an error instead of sleeping until the reset. The variable has no default, so overnight setups keep their current behaviour until someone sets it.

The cap leads the GitHub release notes, which run to about fifty entries. Also in the release: a model-switch bug that could spend usage credits without asking is fixed, OpenTelemetry gets new fields for auto mode decisions, and quitting no longer deletes a worktree that may hold unpushed commits.

Waiting on a usage limit

You turn on the retry watchdog with CLAUDE_CODE_RETRY_WATCHDOG=1. It is meant for runs nobody is watching. Without it, Claude Code gives up on a request after 10 retries. With it on, Claude Code keeps retrying through 429 and overload errors for up to 300 tries, and when it hits a plan usage limit it waits for the window to reset instead of stopping.

A write-up on note.com spells out where that hurts: if the reset is five hours away, the watchdog sits silently for five hours, and deliverables due at 7:00 AM show up at noon. The new variable takes milliseconds and sets the longest wait you will accept. When a 429 response’s reset falls beyond it, the request ends with that 429 and logs an api_request_usage_limit_wait_too_long event.

The same author warns that the setting means “don’t wait,” not “succeed.” A request that ends is simply finished unless something picks it up, so the advice is to decide where it gets handed off before choosing a value.

Two older rules already limited this mode. Since 2.1.295, released October 8, CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS has capped the total time it spends waiting through 429 and 529 responses. And since 2.1.239, released August 21, persistent retry has failed at once on spend-limit and out-of-credits errors. What 2.1.301 adds is a budget for usage-limit waits alone. A run can now keep riding out overload errors under the total cap and still refuse to wait for a plan reset that is far off.

Switching models mid-conversation

Of the fixes, the model-switch one is the one that costs money. Switching to a model with a smaller context window could spend usage credits on a summary by the previous model without asking first. In 2.1.301, a conversation too long for the new model gets summarized by the previous model as the first step of the switch.

Three related fixes deal with models you didn’t choose. Behind an LLM gateway whose responses name a different model than the one requested, conversations were compacted over and over on a model you didn’t pick. The fable and best aliases errored on the Anthropic API when the newest Fable model was not available to your organization; Claude Code now retries once on the previous Fable model. Switching to a model whose name contains application-inference-profile no longer runs your awsAuthRefresh command when the provider is not Bedrock.

Auto mode in telemetry

OpenTelemetry tool_decision events now carry classifier_verdict and permission_mode, so a decision by the auto mode classifier can be told apart from one made by a permission rule. With OTEL_LOG_TOOL_DETAILS=1, a block also carries classifier_category, which names the built-in rule it matched. A day later, on October 16, release 2.1.302 fixed classifier_category missing from most auto mode classifier blocks, so on release day the field was mostly empty.

The claude-api skill also gets OpenTelemetry tracing guidance, including how to set up trace destinations with the ant CLI. That fits with Anthropic’s recent OpenTelemetry export for the Messages API, which is in public beta.

Fixes that change behaviour

Most of the remaining 2.1.301 entries are terminal rendering and UI fixes. These are the ones that change what a tool returns or what you have to update:

  • Grep and Glob reported no matches when the search program failed before returning anything. They now return an error saying the search failed.
  • The Read tool no longer reads binary files such as .xlsm, .parquet, .epub and .heic as text.
  • Workflow agents sometimes skipped their step, and the run still reported success, after reading the harness note that their task text carries no user authority.
  • A tool call cut off during its permission check by a message sent mid-turn was reported to the model as rejected by the user.
  • A full disk that blocked the login refresh produced a misleading “Please run /login”. The error now names the disk and says to delete files.
  • For mod authors: a hook’s .catch handler now runs only when the hook throws or times out, and $.env.set resolves with {}, or with { deny } giving the reason when the write is not made.
  • Vim mode gets the % motion for jumping to the matching bracket, alone or with d, c or y. Escape no longer leaves it stuck in INSERT on a busy machine.
  • The VS Code panel renders LaTeX math, both $$ and \[ … \] blocks and inline math.

Our analysis

What we checked

On October 18 we searched the 2.1.300 and 2.1.301 builds of Claude Code for the retry and telemetry code, and read the settings and monitoring docs.

How we check stories

The release notes hold up, but the cap is narrower than “stop waiting” suggests. It is a second budget next to the existing total one, it applies only to waits on plan usage limits, and it does nothing until you set it. The extensions added to the Read fix run well past the four the notes list.

  • When the variable is unset, the cap is infinite. The variable does not exist in 2.1.300.
  • The budget is cumulative per request. It counts only 429s whose anthropic-ratelimit-unified-status header is rejected, meaning a plan usage limit, and checks them against the server’s retry-after value. The older total cap still applies to the same waits, and whichever limit is smaller wins.
  • Both versions limit a single wait to 6 hours. Our inference is that a reset further away than that was waited out in 6-hour sleeps.
  • classifier_verdict takes four values: allow, block, unavailable and no_verdict. classifier_category appears only on blocks and draws on 73 built-in names plus 6 Cowork names, such as credential_leakage, git_destructive and production_deploy.
  • The Read fix adds 27 extensions, from 94 to 121, among them .npy, .pickle, .whl and .zst. .svg is still read as text.
  • As of October 18, the settings page lists no watchdog variable, and the monitoring page lists neither classifier field.
  • Going by the code (we did not run it), the self-hosted runner starts its sessions with the watchdog turned on. Runner users are already in this mode, and the new cap only applies to them once they set it.

No comments yet. Be the first.

Join the conversation

Sign in to leave a comment. It appears after moderation.