Skip to content

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

Clear use_cloud missing-key error; captcha cloud hint only for non-cloud browsers

Gregor Žuničf0af8268b8ea
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index 783889764..4bfd19844 100644
--- a/browser_use/agent/service.py
+++ b/browser_use/agent/service.py
@@ -61,6 +61,7 @@ from browser_use.agent.views import (
PlanItem,
StepMetadata,
)
+from browser_use.browser.cloud.views import CloudBrowserAuthError
from browser_use.browser.events import _get_timeout
from browser_use.browser.session import DEFAULT_BROWSER_PROFILE
from browser_use.browser.views import BrowserStateSummary
@@ -1660,10 +1661,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
if judgement.failure_reason:
judge_log += f' Failure Reason: {judgement.failure_reason}\n'
if judgement.reached_captcha:
- self.logger.warning(
- 'Agent was blocked by a captcha. Cloud browsers include stealth fingerprinting and proxy rotation to avoid this.\n'
- ' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=captcha_nudge'
- )
+ self._log_cloud_captcha_hint()
judge_log += f' {judgement.reasoning}\n'
self.logger.info(judge_log)
@@ -2161,8 +2159,27 @@ class Agent(Generic[Context, AgentStructuredOutput]):
self.logger.debug(message)
return message
- def _log_final_outcome_messages(self) -> None:
+ def _log_cloud_captcha_hint(self) -> None:
+ """Point local-browser users at cloud browsers after a captcha block, at most once per run."""
+ if getattr(self, '_cloud_captcha_hint_logged', False) or not CONFIG.BROWSER_USE_CLOUD_HINTS:
+ return
+ session = self.browser_session
+ if session is not None:
+ profile = session.browser_profile
+ host = urlparse(session.cdp_url or '').hostname or ''
+ if profile.use_cloud or profile.cloud_browser_params is not None or host.endswith('.browser-use.com'):
+ return # already on a Browser Use cloud browser
+ self._cloud_captcha_hint_logged = True
+ self.logger.warning(
+ 'Agent was blocked by a captcha. Cloud browsers include stealth fingerprinting and proxy rotation to avoid this.\n'
+ ' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=captcha_nudge\n'
+ ' Silence this hint: BROWSER_USE_CLOUD_HINTS=false'
+ )
+
+ def _log_final_outcome_messages(self, cloud_auth_failed: bool = False) -> None:
"""Log helpful messages to user based on agent run outcome"""
+ if cloud_auth_failed:
+ return # the missing/invalid key message already says what to do; it is not a bug to report
# Check if agent failed
is_successful = self.history.is_successful()
@@ -2176,10 +2193,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
has_captcha_issue = any(keyword in final_result_str for keyword in captcha_keywords)
if has_captcha_issue:
- self.logger.warning(
- 'Agent was blocked by a captcha. Cloud browsers include stealth fingerprinting and proxy rotation to avoid this.\n'
- ' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=captcha_nudge'
- )
+ self._log_cloud_captcha_hint()
# General failure message
self.logger.info('')
@@ -2510,7 +2524,9 @@ class Agent(Generic[Context, AgentStructuredOutput]):
loop = asyncio.get_event_loop()
agent_run_error: str | None = None # Initialize error tracking variable
+ cloud_auth_failed = False
self._force_exit_telemetry_logged = False # ADDED: Flag for custom telemetry on force exit
+ self._cloud_captcha_hint_logged = False
should_delay_close = False
# Set up the signal handler with callbacks specific to this agent
@@ -2669,7 +2685,12 @@ class Agent(Generic[Context, AgentStructuredOutput]):
return self.history
except Exception as e:
- self.logger.error(f'Agent run failed with exception: {e}', exc_info=True)
+ if isinstance(e, CloudBrowserAuthError):
+ # Actionable config error: show the message once, without a traceback.
+ cloud_auth_failed = True
+ self.logger.error(f'Agent run failed: {e}')
+ else:
+ self.logger.error(f'Agent run failed with exception: {e}', exc_info=True)
agent_run_error = str(e)
raise e
@@ -2717,7 +2738,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
self.eventbus.dispatch(output_event)
# Log final messages to user based on outcome
- self._log_final_outcome_messages()
+ self._log_final_outcome_messages(cloud_auth_failed=cloud_auth_failed)
# Stop the event bus gracefully, waiting for all events to be processed
# Configurable via TIMEOUT_AgentEventBusStop env var (default: 3.0s)
diff --git a/browser_use/browser/cloud/cloud.py b/browser_use/browser/cloud/cloud.py
index 13ae07833..76d34b099 100644
--- a/browser_use/browser/cloud/cloud.py
+++ b/browser_use/browser/cloud/cloud.py
@@ -17,6 +17,24 @@ logger = logging.getLogger(__name__)
_BROWSER_API_VERSIONS = ('v2', 'v3', 'v4')
+MISSING_API_KEY_MESSAGE = (
+ 'BROWSER_USE_API_KEY is not set. Browser(use_cloud=True) needs a Browser Use Cloud API key.\n'
+ ' 1. Create a key (free to start): '
+ 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud\n'
+ ' 2. Set it: export BROWSER_USE_API_KEY=your-key (or put it in .env and call load_dotenv())'
+)
+
+
+def resolve_api_key() -> str | None:
+ """Return the Browser Use Cloud API key from BROWSER_USE_API_KEY, then the saved auth config."""
+ api_token = os.getenv('BROWSER_USE_API_KEY')
+ if api_token:
+ return api_token
+ try:
+ return CloudAuthConfig.load_from_file().api_token
+ except Exception:
+ return None
+
class CloudBrowserClient:
"""Client for browser-use cloud browser service."""
@@ -77,22 +95,9 @@ class CloudBrowserClient:
Returns:
CloudBrowserResponse: Contains CDP URL and other browser info
"""
- # Try to get API key from environment variable first, then auth config
- api_token = os.getenv('BROWSER_USE_API_KEY')
-
+ api_token = resolve_api_key()
if not api_token:
- # Fallback to auth config file
- try:
- auth_config = CloudAuthConfig.load_from_file()
- api_token = auth_config.api_token
- except Exception:
- pass
-
- if not api_token:
- raise CloudBrowserAuthError(
- 'BROWSER_USE_API_KEY is not set. To use cloud browsers, get a key at:\n'
- 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud'
- )
+ raise CloudBrowserAuthError(MISSING_API_KEY_MESSAGE)
headers = {'X-Browser-Use-API-Key': api_token, 'Content-Type': 'application/json', **(extra_headers or {})}
@@ -165,22 +170,9 @@ class CloudBrowserClient:
if not session_id:
raise CloudBrowserError('No session ID provided and no current session available')
- # Try to get API key from environment variable first, then auth config
- api_token = os.getenv('BROWSER_USE_API_KEY')
-
- if not api_token:
- # Fallback to auth config file
- try:
- auth_config = CloudAuthConfig.load_from_file()
- api_token = auth_config.api_token
- except Exception:
- pass
-
+ api_token = resolve_api_key()
if not api_token:
- raise CloudBrowserAuthError(
- 'BROWSER_USE_API_KEY is not set. To use cloud browsers, get a key at:\n'
- 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud'
- )
+ raise CloudBrowserAuthError(MISSING_API_KEY_MESSAGE)
headers = {'X-Browser-Use-API-Key': api_token, 'Content-Type': 'application/json', **(extra_headers or {})}
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.py
index c45f1213e..ba8779140 100644
--- a/browser_use/browser/session.py
+++ b/browser_use/browser/session.py
@@ -21,7 +21,13 @@ from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
from uuid_extensions import uuid7str
from browser_use.browser._cdp_timeout import TimeoutWrappedCDPClient
-from browser_use.browser.cloud.cloud import CloudBrowserAuthError, CloudBrowserClient, CloudBrowserError
+from browser_use.browser.cloud.cloud import (
+ MISSING_API_KEY_MESSAGE,
+ CloudBrowserAuthError,
+ CloudBrowserClient,
+ CloudBrowserError,
+ resolve_api_key,
+)
# CDP logging is now handled by setup_logging() in logging_config.py
# It automatically sets CDP logs to the same level as browser_use logs
@@ -54,6 +60,7 @@ from browser_use.browser.events import (
)
from browser_use.browser.profile import BrowserProfile, ProxySettings
from browser_use.browser.views import BrowserStateSummary, TabInfo
+from browser_use.config import CONFIG
from browser_use.dom.views import DOMRect, EnhancedDOMTreeNode, SerializedDOMState, TargetInfo
from browser_use.observability import observe_debug
from browser_use.utils import _log_pretty_url, create_task_with_error_handling, is_new_tab_page
@@ -726,11 +733,20 @@ class BrowserSession(BaseModel):
@observe_debug(ignore_input=True, ignore_output=True, name='browser_session_start')
async def start(self) -> None:
"""Start the browser session."""
+ self._raise_if_cloud_api_key_missing()
start_event = self.event_bus.dispatch(BrowserStartEvent())
await start_event
# Ensure any exceptions from the event handler are propagated
await start_event.event_result(raise_if_any=True, raise_if_none=False)
+ def _raise_if_cloud_api_key_missing(self) -> None:
+ """Fail fast with one clear message instead of letting the event bus log the error several times."""
+ profile = self.browser_profile
+ if self.cdp_url or not (profile.use_cloud or profile.cloud_browser_params is not None):
+ return
+ if not resolve_api_key():
+ raise CloudBrowserAuthError(MISSING_API_KEY_MESSAGE)
+
async def kill(self) -> None:
"""Kill the browser session and reset all state."""
self._intentional_stop = True
@@ -897,7 +913,7 @@ class BrowserSession(BaseModel):
details={'cdp_url': self.cdp_url, 'is_local': self.is_local},
)
)
- if self.is_local and not isinstance(e, (CloudBrowserAuthError, CloudBrowserError)):
+ if self.is_local and CONFIG.BROWSER_USE_CLOUD_HINTS and not isinstance(e, (CloudBrowserAuthError, CloudBrowserError)):
self.logger.warning(
'Local browser failed to start. Cloud browsers require no local install and work out of the box.\n'
' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=browser_launch_failure'
diff --git a/browser_use/config.py b/browser_use/config.py
index 1ac9b49ce..10909a131 100644
--- a/browser_use/config.py
+++ b/browser_use/config.py
@@ -183,6 +183,10 @@ class OldConfig:
def BROWSER_USE_VERSION_CHECK(self) -> bool:
return os.getenv('BROWSER_USE_VERSION_CHECK', 'true').lower()[:1] in 'ty1'
+ @property
+ def BROWSER_USE_CLOUD_HINTS(self) -> bool:
+ return os.getenv('BROWSER_USE_CLOUD_HINTS', 'true').lower()[:1] in 'ty1'
+
@property
def WIN_FONT_DIR(self) -> str:
return os.getenv('WIN_FONT_DIR', 'C:\\Windows\\Fonts')
@@ -226,6 +230,7 @@ class FlatEnvConfig(BaseSettings):
IS_IN_EVALS: bool = Field(default=False)
WIN_FONT_DIR: str = Field(default='C:\\Windows\\Fonts')
BROWSER_USE_VERSION_CHECK: bool = Field(default=True)
+ BROWSER_USE_CLOUD_HINTS: bool = Field(default=True)
# MCP-specific env vars
BROWSER_USE_CONFIG_PATH: str | None = Field(default=None)
diff --git a/tests/ci/test_cloud_hints.py b/tests/ci/test_cloud_hints.py
new file mode 100644
index 000000000..15d9f539a
--- /dev/null
+++ b/tests/ci/test_cloud_hints.py
@@ -0,0 +1,101 @@
+"""Cloud browser messages: a clear missing-key error and captcha hints only where they help."""
+
+import logging
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from browser_use import Agent
+from browser_use.browser.cloud.cloud import CloudBrowserAuthError, CloudBrowserClient, resolve_api_key
+from browser_use.browser.profile import BrowserProfile
+from browser_use.browser.session import BrowserSession
+from browser_use.sync.auth import CloudAuthConfig
+from tests.ci.conftest import create_mock_llm
+
+
+def records():
+ """Capture browser_use log records (the browser_use logger does not propagate to root)."""
+ captured: list[logging.LogRecord] = []
+
+ class _ListHandler(logging.Handler):
+ def emit(self, record):
+ captured.append(record)
+
+ handler = _ListHandler(level=logging.DEBUG)
+ logger = logging.getLogger('browser_use')
+ logger.addHandler(handler)
+ yield captured
+ logger.removeHandler(handler)
+
+
+def no_api_key(monkeypatch, tmp_path):
+ monkeypatch.delenv('BROWSER_USE_API_KEY', raising=False)
+ monkeypatch.setenv('BROWSER_USE_CONFIG_DIR', str(tmp_path))
+
+
+def test_resolve_api_key_prefers_env_then_saved_login(no_api_key, monkeypatch):
+ assert resolve_api_key() is None
+
+ CloudAuthConfig(api_token='saved-token', user_id='u', authorized_at=None).save_to_file()
+ assert resolve_api_key() == 'saved-token'
+
+ monkeypatch.setenv('BROWSER_USE_API_KEY', 'env-token')
+ assert resolve_api_key() == 'env-token'
+
+
+async def test_use_cloud_without_key_fails_before_any_request(no_api_key):
+ session = BrowserSession(use_cloud=True)
+ with patch.object(CloudBrowserClient, 'create_browser', new_callable=AsyncMock) as create_browser:
+ with pytest.raises(CloudBrowserAuthError) as exc_info:
+ await session.start()
+
+ create_browser.assert_not_awaited()
+ message = str(exc_info.value)
+ assert 'BROWSER_USE_API_KEY is not set' in message
+ assert 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud' in message
+ assert 'export BROWSER_USE_API_KEY=' in message
+
+
+async def test_agent_logs_missing_key_once_without_traceback(no_api_key, records):
+ agent = Agent(task='open example.com', llm=create_mock_llm(), browser_session=BrowserSession(use_cloud=True))
+
+ with pytest.raises(CloudBrowserAuthError):
+ await agent.run(max_steps=1)
+
+ key_errors = [r for r in records if r.levelno >= logging.ERROR and 'BROWSER_USE_API_KEY is not set' in r.getMessage()]
+ assert len(key_errors) == 1
+ assert key_errors[0].exc_info is None
+ assert not any('Open a short issue on GitHub' in r.getMessage() for r in records)
+
+
+def _captcha_hints(records) -> int:
+ return sum('blocked by a captcha' in r.getMessage() for r in records)
+
+
+ 'session_kwargs, expected',
+ [
+ ({'browser_profile': BrowserProfile(headless=True)}, 1),
+ ({'use_cloud': True}, 0),
+ ({'cdp_url': 'wss://0e5c5a0e-1111-2222-3333-444455556666.cdp1.browser-use.com'}, 0),
+ ({'cdp_url': 'wss://connect.example-provider.com'}, 1),
+ ],
+)
+async def test_captcha_hint_only_for_non_browser_use_browsers_and_once_per_run(records, session_kwargs, expected):
+ agent = Agent(task='t', llm=create_mock_llm(), browser_session=BrowserSession(**session_kwargs))
+
+ agent._log_cloud_captcha_hint()
+ agent._log_cloud_captcha_hint()
+
+ assert _captcha_hints(records) == expected
+
+
+async def test_cloud_hints_can_be_silenced(records, monkeypatch):
+ monkeypatch.setenv('BROWSER_USE_CLOUD_HINTS', 'false')
+ agent = Agent(task='t', llm=create_mock_llm(), browser_session=BrowserSession(browser_profile=BrowserProfile(headless=True)))
+
+ agent._log_cloud_captcha_hint()
+
+ assert _captcha_hints(records) == 0