browser-use/browser-use · error · RuntimeError

Session ID is required for scroll operations

Error message

Session ID is required for scroll operations

What it means

The 'required available_file_paths not provided' raise from the not-in-kwargs branch: the action declares available_file_paths with no default and neither the caller nor the agent context supplied the allow-list. The registry treats an unrestricted/unknown file scope as an error rather than silently allowing arbitrary paths.

Source

Thrown at browser_use/actor/mouse.py:101

		await self._client.send.Input.dispatchMouseEvent(
			params,
			session_id=self._session_id,
		)

	async def move(self, x: int, y: int, steps: int = 1) -> None:
		"""Move mouse to the specified coordinates."""
		# TODO: Implement smooth movement with multiple steps if needed
		_ = steps  # Acknowledge parameter for future use

		params: 'DispatchMouseEventParameters' = {'type': 'mouseMoved', 'x': x, 'y': y}
		await self._client.send.Input.dispatchMouseEvent(params, session_id=self._session_id)

	async def scroll(
		self, x: int | None = None, y: int | None = None, delta_x: int | None = None, delta_y: int | None = None
	) -> None:
		"""Scroll the page using robust CDP methods."""
		if not self._session_id:
			raise RuntimeError('Session ID is required for scroll operations')

		# Get viewport dimensions (used to resolve x/y when the caller doesn't specify a coordinate)
		try:
			layout_metrics = await self._client.send.Page.getLayoutMetrics(session_id=self._session_id)
			viewport_width = layout_metrics['layoutViewport']['clientWidth']
			viewport_height = layout_metrics['layoutViewport']['clientHeight']
		except Exception:
			viewport_width = viewport_height = 0

		scroll_x, scroll_y = _resolve_scroll_anchor(x, y, viewport_width, viewport_height)

		# Calculate scroll deltas (positive = down/right)
		scroll_delta_x = delta_x or 0
		scroll_delta_y = delta_y or 0

		# Method 1: Try mouse wheel event (most reliable)
		try:
			await self._client.send.Input.dispatchMouseEvent(

View on GitHub (pinned to 6c73fced2f)

Solutions

1. Pass the allow-list explicitly: await my_action(..., available_file_paths=['/workspace/**']).
2. Set Agent(available_file_paths=[...]) so injection has a value.
3. Give the parameter a default in your custom action and enforce your own path checks.

Example fix

# before
await export_csv(rows=[...])

# after
await export_csv(rows=[...], available_file_paths=['/workspace/export.csv'])

from inspect import signature, Parameter

def file_paths_missing(func, provided: dict) -> bool:
    p = signature(func).parameters.get('available_file_paths')
    return p is not None and p.default is Parameter.empty and 'available_file_paths' not in provided

def requires_available_file_paths(func) -> bool:
    p = inspect.signature(func).parameters.get('available_file_paths')
    return p is not None and p.default is inspect.Parameter.empty

try:
    await action(**kwargs)
except ValueError as e:
    if 'requires available_file_paths' in str(e):
        await action(**kwargs, available_file_paths=ALLOWED_PATHS)

When it happens

Trigger: await my_file_action(...) with no available_file_paths keyword while the action signature requires it; or an Agent run where available_file_paths was never configured and a custom action copies the built-in file tools' signature.

Common situations: Custom file actions mirrored from write_file/read_file; standalone Tools in tests; agent configured without available_file_paths but the task routes to a file action.

Related errors

• Could not parse arrow function: {page_function[:50]}...
• Failed to click element: {e}
• Failed to get object ID for element
• Element is not visible or has no bounding box
• Target element is not visible

AI-assisted analysis of browser-use/browser-use@6c73fced2f (2026-08-14). Data as JSON: /api/errors/fb37e1b57c3dc877. Report an issue: GitHub.