Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

Let truncation errors switch to the fallback LLM

Saurav Pandadb70a813c1f5
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index fe325c74a..353187605 100644
--- a/browser_use/agent/service.py
+++ b/browser_use/agent/service.py
@@ -25,7 +25,7 @@ from browser_use.agent.cloud_events import (
)
from browser_use.agent.message_manager.utils import save_conversation
from browser_use.llm.base import BaseChatModel
-from browser_use.llm.exceptions import ModelProviderError, ModelRateLimitError
+from browser_use.llm.exceptions import ModelOutputTruncatedError, ModelProviderError, ModelRateLimitError
from browser_use.llm.messages import BaseMessage, ContentPartImageParam, ContentPartTextParam, UserMessage
from browser_use.tokens.service import TokenCost
@@ -1991,8 +1991,10 @@ class Agent(Generic[Context, AgentStructuredOutput]):
# 402: Insufficient credits/payment required - fallback to different provider
# 429: Rate limit exceeded
# 500, 502, 503, 504: Server errors
+ # ModelOutputTruncatedError: the same request would truncate identically on
+ # this model, but a fallback with a different output cap can succeed
retryable_status_codes = {401, 402, 429, 500, 502, 503, 504}
- is_retryable = isinstance(error, ModelRateLimitError) or (
+ is_retryable = isinstance(error, (ModelRateLimitError, ModelOutputTruncatedError)) or (
hasattr(error, 'status_code') and error.status_code in retryable_status_codes
)
diff --git a/browser_use/llm/anthropic/chat.py b/browser_use/llm/anthropic/chat.py
index d466dced3..dc531fa24 100644
--- a/browser_use/llm/anthropic/chat.py
+++ b/browser_use/llm/anthropic/chat.py
@@ -21,7 +21,7 @@ from pydantic import BaseModel
from browser_use.llm.anthropic.serializer import AnthropicMessageSerializer
from browser_use.llm.base import BaseChatModel
-from browser_use.llm.exceptions import ModelProviderError, ModelRateLimitError
+from browser_use.llm.exceptions import ModelOutputTruncatedError, ModelProviderError, ModelRateLimitError
from browser_use.llm.messages import BaseMessage
from browser_use.llm.schema import SchemaOptimizer
from browser_use.llm.views import ChatInvokeCompletion, ChatInvokeUsage
@@ -390,12 +390,11 @@ class ChatAnthropic(BaseChatModel):
# A tool_use block cut off at max_tokens produces incomplete JSON that fails
# validation with a misleading parse error — surface the real cause instead.
if response.stop_reason == 'max_tokens':
- raise ModelProviderError(
+ raise ModelOutputTruncatedError(
message=(
f'Model output was truncated at max_tokens={self.max_tokens}; the structured'
' output is incomplete. Increase max_tokens or request shorter output.'
),
- status_code=400,
model=self.name,
)
diff --git a/browser_use/llm/exceptions.py b/browser_use/llm/exceptions.py
index 809edcc18..cd959b39c 100644
--- a/browser_use/llm/exceptions.py
+++ b/browser_use/llm/exceptions.py
@@ -27,3 +27,20 @@ class ModelRateLimitError(ModelProviderError):
model: str | None = None,
):
super().__init__(message, status_code, model)
+
+
+class ModelOutputTruncatedError(ModelProviderError):
+ """Structured output was cut off at an output-token limit (finish_reason='length' /
+ stop_reason='max_tokens').
+
+ Retrying the same request would truncate identically (status 400 keeps it out of
+ same-provider retry loops), but switching to a fallback LLM with a different output
+ cap can succeed — the agent's fallback logic treats this as switchable.
+ """
+
+ def __init__(
+ self,
+ message: str,
+ model: str | None = None,
+ ):
+ super().__init__(message, status_code=400, model=model)
diff --git a/browser_use/llm/google/chat.py b/browser_use/llm/google/chat.py
index e831c6d6a..15031a1dd 100644
--- a/browser_use/llm/google/chat.py
+++ b/browser_use/llm/google/chat.py
@@ -14,7 +14,7 @@ from google.genai.types import MediaModality
from pydantic import BaseModel
from browser_use.llm.base import BaseChatModel
-from browser_use.llm.exceptions import ModelProviderError
+from browser_use.llm.exceptions import ModelOutputTruncatedError, ModelProviderError
from browser_use.llm.google.serializer import GoogleMessageSerializer
from browser_use.llm.messages import BaseMessage
from browser_use.llm.schema import SchemaOptimizer
@@ -206,13 +206,12 @@ class ChatGoogle(BaseChatModel):
if self.max_output_tokens is not None
else "the model's output token limit"
)
- raise ModelProviderError(
+ raise ModelOutputTruncatedError(
message=(
f'Model output was truncated at {cap};'
' the structured output is incomplete. Increase max_output_tokens or request'
' shorter output.'
),
- status_code=400,
model=self.name,
)
diff --git a/browser_use/llm/openai/chat.py b/browser_use/llm/openai/chat.py
index 476ddf6d2..e915bca94 100644
--- a/browser_use/llm/openai/chat.py
+++ b/browser_use/llm/openai/chat.py
@@ -12,7 +12,7 @@ from openai.types.shared_params.response_format_json_schema import JSONSchema, R
from pydantic import BaseModel
from browser_use.llm.base import BaseChatModel
-from browser_use.llm.exceptions import ModelProviderError, ModelRateLimitError
+from browser_use.llm.exceptions import ModelOutputTruncatedError, ModelProviderError, ModelRateLimitError
from browser_use.llm.messages import BaseMessage
from browser_use.llm.openai.serializer import OpenAIMessageSerializer
from browser_use.llm.schema import SchemaOptimizer
@@ -289,13 +289,12 @@ class ChatOpenAI(BaseChatModel):
if self.max_completion_tokens is not None
else "the model's output token limit"
)
- raise ModelProviderError(
+ raise ModelOutputTruncatedError(
message=(
f'Model output was truncated at {cap};'
' the structured output is incomplete. Increase max_completion_tokens or request'
' shorter output.'
),
- status_code=400,
model=self.name,
)
diff --git a/tests/ci/test_llm_output_truncation.py b/tests/ci/test_llm_output_truncation.py
index 08b1b0dcb..6a777291c 100644
--- a/tests/ci/test_llm_output_truncation.py
+++ b/tests/ci/test_llm_output_truncation.py
@@ -91,3 +91,22 @@ async def test_truncation_error_readable_when_cap_unset(httpserver):
assert 'truncated' in str(exc_info.value)
assert 'None' not in str(exc_info.value), f'error message leaks None: {exc_info.value}'
+
+
+def test_truncation_error_triggers_fallback_llm_switch(tmp_path):
+ """A truncation error must allow switching to a configured fallback LLM — a
+ fallback with a different output cap can succeed where the primary truncated."""
+ from browser_use.agent.service import Agent
+ from browser_use.llm.exceptions import ModelOutputTruncatedError
+ from tests.ci.conftest import create_mock_llm
+
+ agent = Agent(
+ task='test fallback on truncation',
+ llm=create_mock_llm(),
+ fallback_llm=create_mock_llm(),
+ file_system_path=str(tmp_path / 'agent-files'),
+ )
+
+ error = ModelOutputTruncatedError(message='Model output was truncated at max_completion_tokens=4096', model='gpt-4o')
+ assert agent._try_switch_to_fallback_llm(error) is True
+ assert agent._using_fallback_llm is True