PDF documents silently inflate context past long-context threshold, causing unrecoverable 'Rate limit reached' with no actionable error

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

When a session reads multiple PDF files, the embedded base64 document blocks silently push the request past the "long context" billing threshold. The API rejects all subsequent requests with 429 rate_limit_error: "Extra usage is required for long context requests.", but the UI only displays a generic "Rate limit reached" message — which implies a temporary, time-based limit. The session becomes permanently unrecoverable:

• Every request fails, regardless of model or effort level
• /compact fails with "Error: Compaction canceled" (the compaction API call itself is rejected)
• Waiting hours does not help (it is not a time-based rate limit)
• Re-authenticating (claude logout / claude login) does not help
• Resuming the session reproduces the error immediately
• Haiku continues to work; only Opus and Sonnet are affected

The /context widget reported 48k/200k tokens (24%), suggesting the token counter does not accurately reflect the true cost of embedded PDF content. The session log (JSONL) is ~5MB and contains 38 document blocks / 76 base64-encoded blobs.

What Should Happen?

1. The /context widget should accurately reflect the true token cost of PDF/document blocks, so users can see they're approaching the threshold before it's too late.

1. Context management should handle this proactively — compact or evict older document blocks before hitting the long-context billing threshold, or warn the user.

1. The error message should be accurate and actionable. Instead of "Rate limit reached", display something like:

> "This session's context exceeds the long-context limit for your plan. To continue: (1) start a new session, (2) enable extra usage with /extra-usage, or (3) switch to a smaller model."

1. /compact must not fail in this state. If the context is too large for Opus/Sonnet, compaction should fall back to a model that can handle it (e.g., Haiku), or use a local truncation strategy.

Error Messages/Logs

[ERROR] API error (attempt 1/11): 429 {"type":"error","error":{"type":"rate_limit_error","message":"Extra usage is required for long context requests."}}

This error repeats for every request across 14+ hours, confirming it is not a transient rate limit. The UI displays only "API Error: Rate limit reached" with no mention of the actual cause.

Steps to Reproduce

1. On a Max subscription plan without extra usage enabled, open a Claude Code session in a directory with ~20+ PDF files
2. Ask Claude to read and process the PDFs — it uses the Read tool, which embeds them as base64 document content blocks
3. Continue working until ~30+ document blocks accumulate in context
4. Observe: every subsequent API request (Opus or Sonnet) fails with "Rate limit reached"
5. Try /compact — it also fails
6. Try switching models, effort levels, re-authenticating, waiting hours — nothing recovers the session
7. Try Haiku — it works, confirming the issue is model/plan-specific, not a true rate limit

Claude Model

Not sure / Multiple models

Is this a regression?

I don't know

Claude Code Version

2.1.59

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

VS Code integrated terminal

Additional Information

Related issues:

• #26575 — 1M context + rate limits = unrecoverable state (compaction blocked) — same compaction catch-22, but triggered by 1M context rather than PDF accumulation
• #26699 — Session permanently stuck on 'Rate limit reached' — same symptoms, /compact also fails
• #28832 — Rate limit prompt shown despite 0% usage on Max plan — same misleading UI
• #28927 — Silent billing change in v2.1.51: 1M context moved to extra-usage-only — explains the underlying billing change

What's distinct about this report: The trigger is specifically PDF document blocks, which are especially problematic because (a) the /context widget drastically underreports their true token cost, giving no warning before the threshold is crossed, and (b) users have no way to know that reading PDFs will push them past a billing boundary that makes the session unrecoverable.

Workaround: Start a fresh session. Use Haiku for PDF extraction to a text/CSV file, then switch to Opus/Sonnet for analysis on the extracted text.