Skip to content

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

Refactor timeout handling in events to use a dedicated function for improved error handling and clarity. This change replaces direct environment variable parsing with a new `_get_timeout` function across multiple event classes, ensuring consistent timeout management.

Magnus Müller73ce26ab3bfe
diff --git a/browser_use/browser/events.py b/browser_use/browser/events.py
index ffa9a00b4..ed2599b91 100644
--- a/browser_use/browser/events.py
+++ b/browser_use/browser/events.py
@@ -12,6 +12,37 @@ from pydantic import BaseModel, Field, field_validator
from browser_use.browser.views import BrowserStateSummary
from browser_use.dom.views import EnhancedDOMTreeNode
+
+def _get_timeout(env_var: str, default: float) -> float | None:
+ """
+ Safely parse environment variable timeout values with robust error handling.
+
+ Args:
+ env_var: Environment variable name (e.g. 'TIMEOUT_NavigateToUrlEvent')
+ default: Default timeout value as float (e.g. 15.0)
+
+ Returns:
+ Parsed float value or the default if parsing fails
+
+ Raises:
+ ValueError: Only if both env_var and default are invalid (should not happen with valid defaults)
+ """
+ # Try environment variable first
+ env_value = os.getenv(env_var)
+ if env_value:
+ try:
+ parsed = float(env_value)
+ if parsed < 0:
+ print(f'Warning: {env_var}={env_value} is negative, using default {default}')
+ return default
+ return parsed
+ except (ValueError, TypeError):
+ print(f'Warning: {env_var}={env_value} is not a valid number, using default {default}')
+
+ # Fall back to default
+ return default
+
+
# ============================================================================
# Agent/Tools -> BrowserSession Events (High-level browser actions)
# ============================================================================
@@ -89,7 +120,7 @@ class NavigateToUrlEvent(BaseEvent[None]):
# existing_tab: PageHandle | None = None # TODO
# time limits enforced by bubus, not exposed to LLM:
- event_timeout: float | None = float(os.getenv('TIMEOUT_NavigateToUrlEvent', '15.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_NavigateToUrlEvent', 15.0) # seconds
class ClickElementEvent(ElementSelectedEvent[dict[str, Any] | None]):
@@ -104,7 +135,7 @@ class ClickElementEvent(ElementSelectedEvent[dict[str, Any] | None]):
# click_count: int = 1 # TODO
# expect_download: bool = False # moved to downloads_watchdog.py
- event_timeout: float | None = float(os.getenv('TIMEOUT_ClickElementEvent', '15.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_ClickElementEvent', 15.0) # seconds
class TypeTextEvent(ElementSelectedEvent[dict | None]):
@@ -114,7 +145,7 @@ class TypeTextEvent(ElementSelectedEvent[dict | None]):
text: str
clear_existing: bool = True
- event_timeout: float | None = float(os.getenv('TIMEOUT_TypeTextEvent', '15.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_TypeTextEvent', 15.0) # seconds
class ScrollEvent(ElementSelectedEvent[None]):
@@ -124,7 +155,7 @@ class ScrollEvent(ElementSelectedEvent[None]):
amount: int # pixels
node: 'EnhancedDOMTreeNode | None' = None # None means scroll page
- event_timeout: float | None = float(os.getenv('TIMEOUT_ScrollEvent', '8.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_ScrollEvent', 8.0) # seconds
class SwitchTabEvent(BaseEvent[TargetID]):
@@ -132,7 +163,7 @@ class SwitchTabEvent(BaseEvent[TargetID]):
target_id: TargetID | None = Field(default=None, description='None means switch to the most recently opened tab')
- event_timeout: float | None = float(os.getenv('TIMEOUT_SwitchTabEvent', '10.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_SwitchTabEvent', 10.0) # seconds
class CloseTabEvent(BaseEvent[None]):
@@ -140,7 +171,7 @@ class CloseTabEvent(BaseEvent[None]):
target_id: TargetID
- event_timeout: float | None = float(os.getenv('TIMEOUT_CloseTabEvent', '10.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_CloseTabEvent', 10.0) # seconds
class ScreenshotEvent(BaseEvent[str]):
@@ -149,7 +180,7 @@ class ScreenshotEvent(BaseEvent[str]):
full_page: bool = False
clip: dict[str, float] | None = None # {x, y, width, height}
- event_timeout: float | None = float(os.getenv('TIMEOUT_ScreenshotEvent', '8.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_ScreenshotEvent', 8.0) # seconds
class BrowserStateRequestEvent(BaseEvent[BrowserStateSummary]):
@@ -160,7 +191,7 @@ class BrowserStateRequestEvent(BaseEvent[BrowserStateSummary]):
cache_clickable_elements_hashes: bool = True
include_recent_events: bool = False
- event_timeout: float | None = float(os.getenv('TIMEOUT_BrowserStateRequestEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_BrowserStateRequestEvent', 30.0) # seconds
# class WaitForConditionEvent(BaseEvent):
@@ -175,19 +206,19 @@ class BrowserStateRequestEvent(BaseEvent[BrowserStateSummary]):
class GoBackEvent(BaseEvent[None]):
"""Navigate back in browser history."""
- event_timeout: float | None = float(os.getenv('TIMEOUT_GoBackEvent', '15.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_GoBackEvent', 15.0) # seconds
class GoForwardEvent(BaseEvent[None]):
"""Navigate forward in browser history."""
- event_timeout: float | None = float(os.getenv('TIMEOUT_GoForwardEvent', '15.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_GoForwardEvent', 15.0) # seconds
class RefreshEvent(BaseEvent[None]):
"""Refresh/reload the current page."""
- event_timeout: float | None = float(os.getenv('TIMEOUT_RefreshEvent', '15.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_RefreshEvent', 15.0) # seconds
class WaitEvent(BaseEvent[None]):
@@ -196,7 +227,7 @@ class WaitEvent(BaseEvent[None]):
seconds: float = 3.0
max_seconds: float = 10.0 # Safety cap
- event_timeout: float | None = float(os.getenv('TIMEOUT_WaitEvent', '60.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_WaitEvent', 60.0) # seconds
class SendKeysEvent(BaseEvent[None]):
@@ -204,7 +235,7 @@ class SendKeysEvent(BaseEvent[None]):
keys: str # e.g., "ctrl+a", "cmd+c", "Enter"
- event_timeout: float | None = float(os.getenv('TIMEOUT_SendKeysEvent', '15.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_SendKeysEvent', 15.0) # seconds
class UploadFileEvent(ElementSelectedEvent[None]):
@@ -213,7 +244,7 @@ class UploadFileEvent(ElementSelectedEvent[None]):
node: 'EnhancedDOMTreeNode'
file_path: str
- event_timeout: float | None = float(os.getenv('TIMEOUT_UploadFileEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_UploadFileEvent', 30.0) # seconds
class GetDropdownOptionsEvent(ElementSelectedEvent[dict[str, str]]):
@@ -223,11 +254,9 @@ class GetDropdownOptionsEvent(ElementSelectedEvent[dict[str, str]]):
node: 'EnhancedDOMTreeNode'
- event_timeout: float | None = float(
- os.getenv(
- 'TIMEOUT_GetDropdownOptionsEvent',
- '15.0',
- )
+ event_timeout: float | None = _get_timeout(
+ 'TIMEOUT_GetDropdownOptionsEvent',
+ 15.0,
) # some dropdowns lazy-load the list of options on first interaction, so we need to wait for them to load (e.g. table filter lists can have thousands of options)
@@ -239,7 +268,7 @@ class SelectDropdownOptionEvent(ElementSelectedEvent[dict[str, str]]):
node: 'EnhancedDOMTreeNode'
text: str # The option text to select
- event_timeout: float | None = float(os.getenv('TIMEOUT_SelectDropdownOptionEvent', '8.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_SelectDropdownOptionEvent', 8.0) # seconds
class ScrollToTextEvent(BaseEvent[None]):
@@ -248,7 +277,7 @@ class ScrollToTextEvent(BaseEvent[None]):
text: str
direction: Literal['up', 'down'] = 'down'
- event_timeout: float | None = float(os.getenv('TIMEOUT_ScrollToTextEvent', '15.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_ScrollToTextEvent', 15.0) # seconds
# ============================================================================
@@ -260,7 +289,7 @@ class BrowserStartEvent(BaseEvent):
cdp_url: str | None = None
launch_options: dict[str, Any] = Field(default_factory=dict)
- event_timeout: float | None = float(os.getenv('TIMEOUT_BrowserStartEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_BrowserStartEvent', 30.0) # seconds
class BrowserStopEvent(BaseEvent):
@@ -268,7 +297,7 @@ class BrowserStopEvent(BaseEvent):
force: bool = False
- event_timeout: float | None = float(os.getenv('TIMEOUT_BrowserStopEvent', '45.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_BrowserStopEvent', 45.0) # seconds
class BrowserLaunchResult(BaseModel):
@@ -283,13 +312,13 @@ class BrowserLaunchEvent(BaseEvent[BrowserLaunchResult]):
# TODO: add executable_path, proxy settings, preferences, extra launch args, etc.
- event_timeout: float | None = float(os.getenv('TIMEOUT_BrowserLaunchEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_BrowserLaunchEvent', 30.0) # seconds
class BrowserKillEvent(BaseEvent):
"""Kill local browser subprocess."""
- event_timeout: float | None = float(os.getenv('TIMEOUT_BrowserKillEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_BrowserKillEvent', 30.0) # seconds
# TODO: replace all Runtime.evaluate() calls with this event
@@ -342,7 +371,7 @@ class BrowserConnectedEvent(BaseEvent):
cdp_url: str
- event_timeout: float | None = float(os.getenv('TIMEOUT_BrowserConnectedEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_BrowserConnectedEvent', 30.0) # seconds
class BrowserStoppedEvent(BaseEvent):
@@ -350,7 +379,7 @@ class BrowserStoppedEvent(BaseEvent):
reason: str | None = None
- event_timeout: float | None = float(os.getenv('TIMEOUT_BrowserStoppedEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_BrowserStoppedEvent', 30.0) # seconds
class TabCreatedEvent(BaseEvent):
@@ -359,7 +388,7 @@ class TabCreatedEvent(BaseEvent):
target_id: TargetID
url: str
- event_timeout: float | None = float(os.getenv('TIMEOUT_TabCreatedEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_TabCreatedEvent', 30.0) # seconds
class TabClosedEvent(BaseEvent):
@@ -371,7 +400,7 @@ class TabClosedEvent(BaseEvent):
# new_focus_target_id: int | None = None
# new_focus_url: str | None = None
- event_timeout: float | None = float(os.getenv('TIMEOUT_TabClosedEvent', '10.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_TabClosedEvent', 10.0) # seconds
# TODO: emit this when DOM changes significantly, inner frame navigates, form submits, history.pushState(), etc.
@@ -388,7 +417,7 @@ class AgentFocusChangedEvent(BaseEvent):
target_id: TargetID
url: str
- event_timeout: float | None = float(os.getenv('TIMEOUT_AgentFocusChangedEvent', '10.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_AgentFocusChangedEvent', 10.0) # seconds
class TargetCrashedEvent(BaseEvent):
@@ -397,7 +426,7 @@ class TargetCrashedEvent(BaseEvent):
target_id: TargetID
error: str
- event_timeout: float | None = float(os.getenv('TIMEOUT_TargetCrashedEvent', '10.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_TargetCrashedEvent', 10.0) # seconds
class NavigationStartedEvent(BaseEvent):
@@ -406,7 +435,7 @@ class NavigationStartedEvent(BaseEvent):
target_id: TargetID
url: str
- event_timeout: float | None = float(os.getenv('TIMEOUT_NavigationStartedEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_NavigationStartedEvent', 30.0) # seconds
class NavigationCompleteEvent(BaseEvent):
@@ -418,7 +447,7 @@ class NavigationCompleteEvent(BaseEvent):
error_message: str | None = None # Error/timeout message if navigation had issues
loading_status: str | None = None # Detailed loading status (e.g., network timeout info)
- event_timeout: float | None = float(os.getenv('TIMEOUT_NavigationCompleteEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_NavigationCompleteEvent', 30.0) # seconds
# ============================================================================
@@ -433,7 +462,7 @@ class BrowserErrorEvent(BaseEvent):
message: str
details: dict[str, Any] = Field(default_factory=dict)
- event_timeout: float | None = float(os.getenv('TIMEOUT_BrowserErrorEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_BrowserErrorEvent', 30.0) # seconds
# ============================================================================
@@ -446,7 +475,7 @@ class SaveStorageStateEvent(BaseEvent):
path: str | None = None # Optional path, uses profile default if not provided
- event_timeout: float | None = float(os.getenv('TIMEOUT_SaveStorageStateEvent', '45.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_SaveStorageStateEvent', 45.0) # seconds
class StorageStateSavedEvent(BaseEvent):
@@ -456,7 +485,7 @@ class StorageStateSavedEvent(BaseEvent):
cookies_count: int
origins_count: int
- event_timeout: float | None = float(os.getenv('TIMEOUT_StorageStateSavedEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_StorageStateSavedEvent', 30.0) # seconds
class LoadStorageStateEvent(BaseEvent):
@@ -464,7 +493,7 @@ class LoadStorageStateEvent(BaseEvent):
path: str | None = None # Optional path, uses profile default if not provided
- event_timeout: float | None = float(os.getenv('TIMEOUT_LoadStorageStateEvent', '45.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_LoadStorageStateEvent', 45.0) # seconds
# TODO: refactor this to:
@@ -478,7 +507,7 @@ class StorageStateLoadedEvent(BaseEvent):
cookies_count: int
origins_count: int
- event_timeout: float | None = float(os.getenv('TIMEOUT_StorageStateLoadedEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_StorageStateLoadedEvent', 30.0) # seconds
# ============================================================================
@@ -498,7 +527,7 @@ class FileDownloadedEvent(BaseEvent):
from_cache: bool = False
auto_download: bool = False # Whether this was an automatic download (e.g., PDF auto-download)
- event_timeout: float | None = float(os.getenv('TIMEOUT_FileDownloadedEvent', '30.0')) # seconds
+ event_timeout: float | None = _get_timeout('TIMEOUT_FileDownloadedEvent', 30.0) # seconds
class AboutBlankDVDScreensaverShownEvent(BaseEvent):