Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Recover Claude sessions from provider context overflow (#1215)

Ali Khokhar36bb28255892
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 83564066..8cc4aeb9 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -609,6 +609,10 @@ upstream request body it will later stream. `BaseProvider` makes that operation
abstract, so a new provider cannot silently omit the commit-boundary validation.
LM Studio composes the OpenAI-chat conversion first and its context-budget probe
second; conversion failure therefore cannot open a stream or run the probe.
+Provider classifiers and preflights report context exhaustion as the neutral
+`CONTEXT_WINDOW_EXCEEDED` execution failure. The Anthropic serializer alone adds
+Claude's `prompt is too long` compaction trigger; providers never encode a
+client-specific recovery phrase.
Providers call the OpenAI request policy for Anthropic-to-OpenAI conversion,
reasoning replay selection, `extra_body`, and chat-completion field normalization.
diff --git a/pyproject.toml b/pyproject.toml
index be53a66d..c5e19f27 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.11.3"
+version = "4.11.4"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/core/anthropic/errors.py b/src/free_claude_code/core/anthropic/errors.py
index 200b1116..3b8374bb 100644
--- a/src/free_claude_code/core/anthropic/errors.py
+++ b/src/free_claude_code/core/anthropic/errors.py
@@ -20,6 +20,7 @@ _ANTHROPIC_ERROR_STATUS_CODES = {
_FAILURE_ERROR_TYPES = {
FailureKind.INVALID_REQUEST: "invalid_request_error",
+ FailureKind.CONTEXT_WINDOW_EXCEEDED: "invalid_request_error",
FailureKind.AUTHENTICATION: "authentication_error",
FailureKind.PERMISSION: "permission_error",
FailureKind.RATE_LIMIT: "rate_limit_error",
@@ -77,11 +78,20 @@ def anthropic_failure_payload(
"""Serialize a canonical execution failure as an Anthropic JSON error."""
return anthropic_error_payload(
error_type=anthropic_error_type_for_failure(failure),
- message=failure.message,
+ message=_anthropic_failure_message(failure),
request_id=request_id,
)
+def _anthropic_failure_message(failure: ExecutionFailure) -> str:
+ """Add client-recognized wording only at the Anthropic wire boundary."""
+ if failure.kind != FailureKind.CONTEXT_WINDOW_EXCEEDED:
+ return failure.message
+ if failure.message.lstrip().lower().startswith("prompt is too long"):
+ return failure.message
+ return f"prompt is too long\n\n{failure.message}"
+
+
def anthropic_status_for_error_type(error_type: str) -> int:
"""Return the standard HTTP status for an Anthropic error type."""
return _ANTHROPIC_ERROR_STATUS_CODES.get(error_type, 500)
diff --git a/src/free_claude_code/core/failures.py b/src/free_claude_code/core/failures.py
index c2dacbf5..9f813ca7 100644
--- a/src/free_claude_code/core/failures.py
+++ b/src/free_claude_code/core/failures.py
@@ -8,6 +8,7 @@ class FailureKind(StrEnum):
"""Stable failure categories shared across execution and wire adapters."""
INVALID_REQUEST = "invalid_request"
+ CONTEXT_WINDOW_EXCEEDED = "context_window_exceeded"
AUTHENTICATION = "authentication"
PERMISSION = "permission"
RATE_LIMIT = "rate_limit"
diff --git a/src/free_claude_code/core/openai_responses/errors.py b/src/free_claude_code/core/openai_responses/errors.py
index 1e288670..4798054b 100644
--- a/src/free_claude_code/core/openai_responses/errors.py
+++ b/src/free_claude_code/core/openai_responses/errors.py
@@ -7,6 +7,7 @@ from free_claude_code.core.failures import ExecutionFailure, FailureKind
_FAILURE_ERROR_TYPES = {
FailureKind.INVALID_REQUEST: "invalid_request_error",
+ FailureKind.CONTEXT_WINDOW_EXCEEDED: "invalid_request_error",
FailureKind.AUTHENTICATION: "authentication_error",
FailureKind.PERMISSION: "permission_error",
FailureKind.RATE_LIMIT: "rate_limit_error",
diff --git a/src/free_claude_code/providers/failure_policy.py b/src/free_claude_code/providers/failure_policy.py
index 412918d5..fe6743ff 100644
--- a/src/free_claude_code/providers/failure_policy.py
+++ b/src/free_claude_code/providers/failure_policy.py
@@ -32,6 +32,7 @@ _INTERNAL_ERROR_MARKERS = frozenset({"internal_server_error", "internal server e
_AUTHENTICATION_MESSAGE = "Provider authentication failed. Check API key."
_RATE_LIMIT_MESSAGE = "Provider rate limit reached. Please retry shortly."
_INVALID_REQUEST_MESSAGE = "Invalid request sent to provider."
+_CONTEXT_WINDOW_EXCEEDED_MESSAGE = "Provider input exceeds the model context window."
_OVERLOADED_MESSAGE = "Provider is currently overloaded. Please retry."
@@ -89,6 +90,13 @@ def overloaded_provider_failure() -> ExecutionFailure:
return _failure(FailureKind.OVERLOADED, 529, _OVERLOADED_MESSAGE, True)
+def context_window_exceeded_provider_failure(
+ message: str = _CONTEXT_WINDOW_EXCEEDED_MESSAGE,
+) -> ExecutionFailure:
+ """Return the canonical non-retryable provider context-window failure."""
+ return _failure(FailureKind.CONTEXT_WINDOW_EXCEEDED, 400, message, False)
+
+
def retryable_transient_status(exc: BaseException) -> int | None:
"""Infer a retryable HTTP-like status from one upstream exception."""
if isinstance(exc, ProviderRecoveryExhausted):
diff --git a/src/free_claude_code/providers/lmstudio/client.py b/src/free_claude_code/providers/lmstudio/client.py
index 243957d8..2916c009 100644
--- a/src/free_claude_code/providers/lmstudio/client.py
+++ b/src/free_claude_code/providers/lmstudio/client.py
@@ -16,7 +16,6 @@ import time
import httpx
from loguru import logger
-from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.core.anthropic import ReasoningReplayMode, get_token_count
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.reasoning import (
@@ -26,6 +25,9 @@ from free_claude_code.core.reasoning import (
)
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.failure_policy import (
+ context_window_exceeded_provider_failure,
+)
from free_claude_code.providers.openai_chat import (
NamedEffortReasoning,
OpenAIChatProfile,
@@ -59,9 +61,8 @@ class LMStudioProvider(OpenAIChatProvider):
# LM Studio truncates the stream silently (no terminal event) when the
# prompt exceeds the loaded context. Refuse clearly over-budget prompts
- # up front with the same "prompt is too long" invalid_request_error the
- # real Anthropic API uses, so Claude Code can compact/retry instead of
- # dying mid-stream.
+ # up front as a context-window failure so protocol adapters can tell their
+ # clients to compact/retry instead of letting the stream die silently.
_CONTEXT_CACHE_TTL_S = 30.0
def __init__(
@@ -98,9 +99,10 @@ class LMStudioProvider(OpenAIChatProvider):
# fired, and letting it through risks a silent LM Studio truncation.
budget = int(loaded_context * 0.9)
if estimate > budget:
- raise InvalidRequestError(
- f"prompt is too long: {estimate} tokens > {budget} "
- f"maximum (90% of loaded LM Studio context {loaded_context})"
+ raise context_window_exceeded_provider_failure(
+ f"Estimated provider input ({estimate} tokens) exceeds the safe "
+ f"LM Studio context budget ({budget} tokens; 90% of loaded "
+ f"context {loaded_context})."
)
def _loaded_context_length(self) -> int | None:
diff --git a/src/free_claude_code/providers/nvidia_nim/client.py b/src/free_claude_code/providers/nvidia_nim/client.py
index a75124bb..252651ac 100644
--- a/src/free_claude_code/providers/nvidia_nim/client.py
+++ b/src/free_claude_code/providers/nvidia_nim/client.py
@@ -1,6 +1,7 @@
"""NVIDIA NIM provider implementation."""
import json
+import re
from collections.abc import Mapping
from typing import Any
@@ -14,6 +15,7 @@ from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningP
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.failure_policy import (
+ context_window_exceeded_provider_failure,
overloaded_provider_failure,
)
from free_claude_code.providers.openai_chat import (
@@ -34,6 +36,10 @@ from .tool_schema import (
)
_DEGRADED_FUNCTION_STATE = "degraded function cannot be invoked"
+_NEGATIVE_MAX_TOKENS_PATTERN = re.compile(
+ r"\bmax_tokens must be at least 1,\s*got\s+-[1-9]\d*\b",
+ re.IGNORECASE,
+)
_PROFILE = OpenAIChatProfile(
NIM_REQUEST_POLICY,
NO_REASONING,
@@ -124,27 +130,50 @@ class NvidiaNimProvider(OpenAIChatProvider):
return None
def _provider_failure_override(self, error: Exception) -> ExecutionFailure | None:
- """Map NVIDIA Cloud Function deployment failure onto canonical overload."""
+ """Classify NVIDIA-specific 400 responses by their actual semantics."""
if not isinstance(error, openai.BadRequestError):
return None
if getattr(error, "status_code", None) != 400:
return None
- body = getattr(error, "body", None)
- if not isinstance(body, Mapping):
- return None
- detail = body.get("detail")
- if not isinstance(detail, str):
- return None
- function_ref, separator, state = detail.lower().partition(": ")
- function_id = function_ref.removeprefix("function id ").strip(" '\"")
- if (
- not separator
- or not function_ref.startswith("function id ")
- or not function_id
- or state.strip() != _DEGRADED_FUNCTION_STATE
- ):
- return None
- return overloaded_provider_failure()
+ bodies = _nim_error_bodies(error)
+ if any(_is_context_window_exhaustion(body) for body in bodies):
+ return context_window_exceeded_provider_failure()
+ if any(_is_degraded_function(body) for body in bodies):
+ return overloaded_provider_failure()
+ return None
+
+
+def _nim_error_bodies(error: Exception) -> tuple[Mapping[str, Any], ...]:
+ body = getattr(error, "body", None)
+ if not isinstance(body, Mapping):
+ return ()
+ nested = body.get("error")
+ if isinstance(nested, Mapping):
+ return body, nested
+ return (body,)
+
+
+def _is_context_window_exhaustion(body: Mapping[str, Any]) -> bool:
+ message = body.get("message")
+ return (
+ body.get("param") == "max_tokens"
+ and isinstance(message, str)
+ and _NEGATIVE_MAX_TOKENS_PATTERN.search(message) is not None
+ )
+
+
+def _is_degraded_function(body: Mapping[str, Any]) -> bool:
+ detail = body.get("detail")
+ if not isinstance(detail, str):
+ return False
+ function_ref, separator, state = detail.lower().partition(": ")
+ function_id = function_ref.removeprefix("function id ").strip(" '\"")
+ return bool(
+ separator
+ and function_ref.startswith("function id ")
+ and function_id
+ and state.strip() == _DEGRADED_FUNCTION_STATE
+ )
def _is_reasoning_budget_rejection(error_text: str) -> bool:
diff --git a/tests/api/test_execution_failure_contract.py b/tests/api/test_execution_failure_contract.py
index b2e86e51..32e98be4 100644
--- a/tests/api/test_execution_failure_contract.py
+++ b/tests/api/test_execution_failure_contract.py
@@ -265,6 +265,45 @@ def test_messages_pre_start_execution_failure_is_correlated_terminal_json() -> N
assert provider.stream_kwargs[0]["request_id"] == request_id
+def test_messages_context_window_failure_triggers_client_compaction() -> None:
+ provider = CanonicalFailureProvider(
+ [],
+ kind=FailureKind.CONTEXT_WINDOW_EXCEEDED,
+ status_code=400,
+ message="Provider input exceeds the model context window.",
+ retryable=False,
+ )
+ resolver_patch, client = _client_for(provider)
+
+ with (
+ resolver_patch,
+ patch("free_claude_code.api.response_streams.trace_event") as trace_mock,
+ client,
+ ):
+ response = client.post("/v1/messages", json=_messages_payload(stream=True))
+
+ request_id = response.headers["request-id"]
+ assert response.status_code == 400
+ assert response.headers["x-should-retry"] == "false"
+ assert response.json() == {
+ "type": "error",
+ "error": {
+ "type": "invalid_request_error",
+ "message": (
+ "prompt is too long\n\n"
+ "Provider input exceeds the model context window.\n\n"
+ f"Request ID: {request_id}"
+ ),
+ },
+ "request_id": request_id,
+ }
+ trace = _terminal_trace(trace_mock)
+ assert trace["failure_kind"] == "context_window_exceeded"
+ assert trace["status_code"] == 400
+ assert trace["error_type"] == "invalid_request_error"
+ assert trace["provider_retryable"] is False
+
+
def test_responses_pre_start_execution_failure_is_correlated_terminal_json() -> None:
provider = CanonicalFailureProvider(
[],
diff --git a/tests/core/test_failure_protocol_mapping.py b/tests/core/test_failure_protocol_mapping.py
index dbf70324..8a795734 100644
--- a/tests/core/test_failure_protocol_mapping.py
+++ b/tests/core/test_failure_protocol_mapping.py
@@ -17,6 +17,11 @@ from free_claude_code.core.openai_responses.errors import (
("kind", "anthropic_type", "openai_type"),
[
(FailureKind.INVALID_REQUEST, "invalid_request_error", "invalid_request_error"),
+ (
+ FailureKind.CONTEXT_WINDOW_EXCEEDED,
+ "invalid_request_error",
+ "invalid_request_error",
+ ),
(FailureKind.AUTHENTICATION, "authentication_error", "authentication_error"),
(FailureKind.PERMISSION, "permission_error", "permission_error"),
(FailureKind.RATE_LIMIT, "rate_limit_error", "rate_limit_error"),
@@ -47,3 +52,31 @@ def test_finalized_status_502_timeout_keeps_existing_api_error_wire_type() -> No
assert anthropic_failure_payload(failure)["error"]["type"] == "api_error"
assert openai_failure_payload(failure)["error"]["type"] == "api_error"
+
+
+def test_only_anthropic_serialization_adds_the_client_compaction_trigger() -> None:
+ failure = ExecutionFailure(
+ kind=FailureKind.CONTEXT_WINDOW_EXCEEDED,
+ status_code=400,
+ message="Provider input exceeds its context window.\n\nRequest ID: req_context",
+ retryable=False,
+ )
+
+ anthropic_error = anthropic_failure_payload(failure)["error"]
+ openai_error = openai_failure_payload(failure)["error"]
+
+ assert anthropic_error == {
+ "type": "invalid_request_error",
+ "message": (
+ "prompt is too long\n\nProvider input exceeds its context window."
+ "\n\nRequest ID: req_context"
+ ),
+ }
+ assert openai_error == {
+ "message": (
+ "Provider input exceeds its context window.\n\nRequest ID: req_context"
+ ),
+ "type": "invalid_request_error",
+ "param": None,
+ "code": None,
+ }
diff --git a/tests/core/test_failures.py b/tests/core/test_failures.py
index 1a2672bb..00a4a580 100644
--- a/tests/core/test_failures.py
+++ b/tests/core/test_failures.py
@@ -14,6 +14,7 @@ from free_claude_code.core.failures import (
def test_failure_kind_has_only_protocol_neutral_semantics() -> None:
assert tuple(FailureKind) == (
FailureKind.INVALID_REQUEST,
+ FailureKind.CONTEXT_WINDOW_EXCEEDED,
FailureKind.AUTHENTICATION,
FailureKind.PERMISSION,
FailureKind.RATE_LIMIT,
@@ -24,6 +25,7 @@ def test_failure_kind_has_only_protocol_neutral_semantics() -> None:
)
assert tuple(kind.value for kind in FailureKind) == (
"invalid_request",
+ "context_window_exceeded",
"authentication",
"permission",
"rate_limit",
diff --git a/tests/providers/test_lmstudio.py b/tests/providers/test_lmstudio.py
index 418918eb..f162c590 100644
--- a/tests/providers/test_lmstudio.py
+++ b/tests/providers/test_lmstudio.py
@@ -7,6 +7,7 @@ import pytest
from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.provider_catalog import LMSTUDIO_DEFAULT_BASE
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.lmstudio import LMStudioProvider
@@ -219,10 +220,20 @@ def test_preflight_context_budget_rejects_request_over_90_percent(lmstudio_provi
"free_claude_code.providers.lmstudio.client.get_token_count",
return_value=901,
),
- pytest.raises(InvalidRequestError, match="prompt is too long"),
+ pytest.raises(ExecutionFailure) as exc_info,
):
lmstudio_provider._preflight_context_budget(make_request())
+ failure = exc_info.value
+ assert failure.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert failure.status_code == 400
+ assert failure.retryable is False
+ assert failure.message == (
+ "Estimated provider input (901 tokens) exceeds the safe LM Studio "
+ "context budget (900 tokens; 90% of loaded context 1000)."
+ )
+ assert "prompt is too long" not in failure.message
+
def test_loaded_context_length_reads_max_across_loaded_models(lmstudio_provider):
response = MagicMock()
diff --git a/tests/providers/test_nvidia_nim_degraded_retry.py b/tests/providers/test_nvidia_nim_degraded_retry.py
index 4b50ea39..067334e8 100644
--- a/tests/providers/test_nvidia_nim_degraded_retry.py
+++ b/tests/providers/test_nvidia_nim_degraded_retry.py
@@ -70,6 +70,28 @@ def _bad_request(
return openai.BadRequestError("Bad Request", response=response, body=body)
+def _context_window_error(
+ *,
+ message: str = (
+ "max_tokens must be at least 1, got -853. (parameter=max_tokens, value=-853)"
+ ),
+ param: str = "max_tokens",
+ nested: bool = False,
+) -> openai.BadRequestError:
+ request = httpx.Request(
+ "POST", "https://integrate.api.nvidia.com/v1/chat/completions"
+ )
+ response = httpx.Response(400, request=request)
+ error_body: dict[str, object] = {
+ "message": message,
+ "type": "BadRequestError",
+ "param": param,
+ "code": 400,
+ }
+ body = {"error": error_body} if nested else error_body
+ return openai.BadRequestError("Bad Request", response=response, body=body)
+
+
def _successful_stream(text: str = "Recovered"):
chunk = MagicMock()
chunk.choices = [
@@ -174,6 +196,74 @@ async def test_degraded_function_exhaustion_is_detailed_redacted_overload() -> N
assert "error_message" not in error_traces[-1]
[email protected]("nested", [False, True])
+async def test_negative_derived_max_tokens_is_context_window_failure(
+ nested: bool,
+) -> None:
+ provider = _nim(_admission())
+
+ with (
+ patch.object(
+ provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ side_effect=_context_window_error(nested=nested),
+ ) as create,
+ pytest.raises(ExecutionFailure) as exc_info,
+ ):
+ [
+ event
+ async for event in provider.stream_response(
+ make_messages_request(), request_id="req_context"
+ )
+ ]
+
+ assert create.await_count == 1
+ failure = exc_info.value
+ assert failure.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert failure.status_code == 400
+ assert failure.retryable is False
+ assert "Mapped message: Provider input exceeds the model context window." in (
+ failure.message
+ )
+ assert "max_tokens must be at least 1, got -853" in failure.message
+ assert "Request ID: req_context" in failure.message
+ assert "prompt is too long" not in failure.message
+
+
+ ("message", "param"),
+ [
+ ("max_tokens must be at least 1, got 0", "max_tokens"),
+ ("max_tokens must be at least 1, got -853", "temperature"),
+ ("max_tokens must be less than or equal to 8192", "max_tokens"),
+ ],
+)
+async def test_other_nim_max_token_errors_remain_invalid_requests(
+ message: str,
+ param: str,
+) -> None:
+ provider = _nim(_admission())
+
+ with (
+ patch.object(
+ provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ side_effect=_context_window_error(message=message, param=param),
+ ) as create,
+ pytest.raises(ExecutionFailure) as exc_info,
+ ):
+ [event async for event in provider.stream_response(make_messages_request())]
+
+ assert create.await_count == 1
+ assert exc_info.value.kind is FailureKind.INVALID_REQUEST
+ assert exc_info.value.status_code == 400
+ assert exc_info.value.retryable is False
+
+
@pytest.mark.parametrize(
"detail",
[
diff --git a/uv.lock b/uv.lock
index 62ee825b..1f84a7f8 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.11.3"
+version = "4.11.4"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },