[BUG] --max-budget-usd stops Max subscription run despite zero API cost and remaining quota

Status Open
Reported on v2.1.221
Maintainer reply None cached
Activity 1 comment · opened Aug 9, 2026

Description

claude -p terminates a Claude.ai Max subscription-backed run with:

Error: Exceeded USD budget (1)

when --max-budget-usd 1.00 is supplied, even though the CLI is authenticated through the Claude.ai subscription, no API credential/provider override is present, the Usage screen reports Total cost: $0.0000, and substantial model quota remains.

The flag is described by claude --help as:

--max-budget-usd <amount>  Maximum dollar amount to spend on API calls (only works with --print)

For subscription-backed usage, no dollar amount was spent on API calls. The observed behavior appears to enforce an undisclosed estimated API-equivalent cost instead.

Steps to reproduce

  1. Sign in to Claude Code using a Claude.ai Max subscription (not an API key).
  2. Confirm claude auth status --json reports authMethod: "claude.ai", subscriptionType: "max", and apiProvider: "firstParty".
  3. Confirm no ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, Bedrock, Vertex, or Foundry override is present.
  4. Run a sufficiently involved print-mode task:
claude -p --model fable --effort high \
  --permission-mode dontAsk \
  --no-session-persistence \
  --max-budget-usd 1.00 \
  "Review a non-trivial repository change and return concise findings."
  1. Observe Error: Exceeded USD budget (1).
  2. Open /usage; observe Total cost: $0.0000 and remaining subscription quota.

Expected behavior

One of:

  • For Claude.ai subscription authentication, --max-budget-usd limits only actual paid API/extra-usage spend and does not terminate included subscription usage.
  • If the intended behavior is to cap estimated dollar-equivalent model consumption regardless of billing source, rename/reword the flag and error so it does not claim an API dollar budget was exceeded.
  • At minimum, make the error distinguish actual billed spend from an estimated-equivalent safety threshold.

Actual behavior

The command terminates at an internal dollar-equivalent threshold while the product simultaneously reports zero API cost and available subscription usage. This makes automation incorrectly conclude that the user's paid subscription capacity is exhausted.

Environment

  • Claude Code: 2.1.221
  • Authentication: Claude.ai OAuth
  • Subscription: Max
  • API provider: firstParty
  • API key/auth-token/cloud-provider overrides: absent
  • OS: macOS
  • Shell: zsh
  • Invocation mode: --print
  • Model: Fable

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗