CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS

Updated October 23, 2026 by Alex Sorokoletov

CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS is a Claude Code environment variable: Caps the total time unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) waits through 429 and 529 responses. Once the elapsed wait passes the cap, the request stops with a capacity-wait-exhausted error rather than retrying further. Default is no cap. Named in the v2.1.295 release notes.[1]. Added in v2.1.295 and still present in v2.1.310. It is listed in the official reference.

How to set it

For one session, export it in the shell that starts Claude Code:

export CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=<value>
claude

To apply it to every session, add it to the env object of a settings file:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS": "<value>"
  }
}

Release notes that mention it

• Claude Code Version Tracker: Undocumented Env Vars, Feature Gates & Models
• claude-code-env-vars-v2-1-301
• claude-code-env-vars-v2-1-295

Related variables

• CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS: Bounds how long unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) waits for a usage-limit reset.
• CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS: Raises the ceiling on the backoff delay when retrying a request that returned a 529 overloaded response.
• CLAUDE_CODE_RETRY_WATCHDOG: Tunes the retry watchdog that detects API calls silently looping without progress.
• CLAUDE_CODE_RETRY_WATCHDOG_SCOPE: Read alongside CLAUDE_CODE_RETRY_WATCHDOG.
• CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS: Governs how unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) rechecks a usage limit that was lifted before its reset, so a headless run can resume once the limit clears.
• CLAUDE_CODE_RETRY_WATCHDOG_SCOPE1
• BASH_MAX_TIMEOUT_MS
• CLAUDE_CODE_MAX_RETRIES: Maximum API request retries.

Frequently asked questions

All variables, searchable: Claude Code environment variables.