Raise on evaluate_js failure instead of returning a null DataSpace

.pre-commit-config.yaml

@@ -88,6 +88,12 @@ repos:
         language: system
         files: ^docs/src/(docs\.json|scripts/check_docs_nav\.py)$
         pass_filenames: false
+      - id: docs-config-defaults
+        name: Check documented session-config defaults against the SDK
+        entry: bash -c "uv run python docs/src/scripts/check_config_docs_defaults.py"
+        language: system
+        files: ^(docs/src/features/sessions/configuration\.mdx|docs/src/scripts/check_config_docs_defaults\.py|packages/notte-sdk/src/notte_sdk/types\.py|packages/notte-core/src/notte_core/config\.toml)$
+        pass_filenames: false
       - id: docs-quickstart-setup-prompt
         name: Inline Quickstart setup prompt
         entry: bash -c "cd docs/src && uv run python scripts/inline_quickstart_setup_prompt.py --check"

docs/src/features/sessions/configuration.mdx

@@ -38,11 +38,11 @@ Customize your session with these options:
 
 ### Common Parameters
 
-<ParamField path="headless" type="boolean" default={true}>
+<ParamField path="headless" type="boolean" default={false}>
   Whether to run the browser in headless mode. Set to `false` to open a live viewer in your browser.
 </ParamField>
 
-<ParamField path="solve_captchas" type="boolean" default={false}>
+<ParamField path="solve_captchas" type="boolean" default={true}>
   Automatically detect and solve captchas (reCAPTCHA, hCaptcha, etc.)
 </ParamField>
 
@@ -63,7 +63,7 @@ Customize your session with these options:
   Browser viewport height in pixels.
 </ParamField>
 
-<ParamField path="browser_type" type="string" default={"chrome"}>
+<ParamField path="browser_type" type="string" default={"chromium"}>
   Browser engine to use: `"chromium"`, or `"chrome"`.
 </ParamField>
 
@@ -81,7 +81,7 @@ Customize your session with these options:
   Connect to an external browser session via Chrome DevTools Protocol URL (e.g., from Kernel.sh or other providers).
 </ParamField>
 
-<ParamField path="use_file_storage" type="boolean" default={false}>
+<ParamField path="use_file_storage" type="boolean" default={true}>
   Enable file storage for uploading/downloading files during the session.
 </ParamField>
 
@@ -97,7 +97,7 @@ Customize your session with these options:
   Default perception type for observations: `"fast"` (simple) or `"deep"` (LLM-powered).
 </ParamField>
 
-<ParamField path="raise_on_failure" type="boolean" default={false}>
+<ParamField path="raise_on_failure" type="boolean" default={true}>
   Raise exceptions when action execution fails instead of returning error results.
 </ParamField>
 

docs/src/scripts/check_config_docs_defaults.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Check documented session-config defaults against the SDK's actual values.
+
+`docs/src/features/sessions/configuration.mdx` is hand-written, so its
+`<ParamField default={...}>` values can silently drift from the code (the page
+said `raise_on_failure` defaults to false for seven months while the config
+said true). This check compares every documented default against the source of
+truth: `SessionStartRequest` field defaults and `notte_core` config values.
+
+Doc param names do not always match field names one-to-one, so the mapping in
+`code_defaults()` is explicit; a documented default with no mapping entry is an
+error, which forces the mapping to grow with the page.
+
+Run from the repo root (the script needs the workspace venv for notte imports):
+    uv run python docs/src/scripts/check_config_docs_defaults.py
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+CONFIGURATION_MDX = REPO_ROOT / "docs" / "src" / "features" / "sessions" / "configuration.mdx"
+
+PARAM_FIELD_RE = re.compile(r'<ParamField\s+path="([^"]+)"[^>]*?\sdefault=(\{[^}]*\}|"[^"]*")')
+
+
+def code_defaults() -> dict[str, Any]:
+    from notte_core.common.config import config
+    from notte_sdk.types import (
+        DEFAULT_HEADLESS_VIEWPORT_HEIGHT,
+        DEFAULT_HEADLESS_VIEWPORT_WIDTH,
+        SessionStartRequest,
+    )
+
+    fields = SessionStartRequest.model_fields
+
+    def field_default(name: str) -> Any:
+        return fields[name].default
+
+    return {
+        "headless": field_default("headless"),
+        "solve_captchas": field_default("solve_captchas"),
+        "proxies": field_default("proxies"),
+        # the docs param is the SDK's idle timeout
+        "timeout_minutes": field_default("idle_timeout_minutes"),
+        # the request fields default to None ("server decides"); the effective
+        # server defaults are these shared constants
+        "viewport_width": DEFAULT_HEADLESS_VIEWPORT_WIDTH,
+        "viewport_height": DEFAULT_HEADLESS_VIEWPORT_HEIGHT,
+        "browser_type": field_default("browser_type"),
+        "use_file_storage": field_default("use_file_storage"),
+        "perception_type": config.perception_type,
+        "raise_on_failure": config.raise_on_session_execution_failure,
+    }
+
+
+def parse_doc_default(token: str) -> Any:
+    """Turn a ParamField default token (`{true}`, `{3}`, `{"chrome"}`, `"fast"`) into a value."""
+    if token.startswith('"'):
+        return token[1:-1]
+    inner = token[1:-1].strip()
+    if inner == "true":
+        return True
+    if inner == "false":
+        return False
+    if inner.startswith('"') and inner.endswith('"'):
+        return inner[1:-1]
+    try:
+        return int(inner)
+    except ValueError:
+        return inner
+
+
+def normalize(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    return value
+
+
+def main() -> int:
+    text = CONFIGURATION_MDX.read_text()
+    expected = code_defaults()
+    errors: list[str] = []
+    checked = 0
+
+    for match in PARAM_FIELD_RE.finditer(text):
+        name, token = match.group(1), match.group(2)
+        doc_value = parse_doc_default(token)
+        if name not in expected:
+            errors.append(
+                f"{name}: documented default {doc_value!r} has no entry in code_defaults(); "
+                "add a mapping to the code's source of truth"
+            )
+            continue
+        checked += 1
+        code_value = normalize(expected[name])
+        if doc_value != code_value or isinstance(doc_value, bool) is not isinstance(code_value, bool):
+            errors.append(f"{name}: docs say {doc_value!r}, code default is {code_value!r}")
+
+    if checked == 0:
+        errors.append(f"no ParamField defaults found in {CONFIGURATION_MDX}; the regex or the page drifted")
+
+    if errors:
+        print(f"{CONFIGURATION_MDX.relative_to(REPO_ROOT)} disagrees with the SDK defaults:")
+        for error in errors:
+            print(f"  - {error}")
+        return 1
+
+    print(f"checked {checked} documented defaults against the SDK: all match")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

packages/notte-browser/src/notte_browser/session.py

@@ -64,7 +64,7 @@
 from notte_core.common.telemetry import track_usage
 from notte_core.credentials.base import BaseVault, LocatorAttributes
 from notte_core.data.space import DataSpace, ImageData, StructuredData, TBaseModel
-from notte_core.errors.actions import InvalidActionError
+from notte_core.errors.actions import ActionExecutionError, InvalidActionError
 from notte_core.errors.base import NotteBaseError
 from notte_core.errors.provider import RateLimitError
 from notte_core.profiling import profiler
@@ -466,6 +466,7 @@ async def aread_emails(
         only_unread: bool | None = None,
         time_window: dt.timedelta | None = None,
         limit: int | None = None,
+        raise_on_failure: bool = False,
     ) -> ExecutionResult:
         if not self._has_any_persona_tool():
             raise ValueError(
@@ -478,23 +479,31 @@ async def aread_emails(
             payload["timedelta"] = time_window
         if limit is not None:
             payload["limit"] = limit
-        return await self.aexecute(**payload)
+        # reads are queries: a tool reporting "nothing yet" is data, not an error,
+        # so polling `while not session.read_emails().success` keeps working
+        return await self.aexecute(raise_on_failure=raise_on_failure, **payload)
 
     def read_emails(
         self,
         *,
         only_unread: bool | None = None,
         time_window: dt.timedelta | None = None,
         limit: int | None = None,
+        raise_on_failure: bool = False,
     ) -> ExecutionResult:
-        return asyncio.run(self.aread_emails(only_unread=only_unread, time_window=time_window, limit=limit))
+        return asyncio.run(
+            self.aread_emails(
+                only_unread=only_unread, time_window=time_window, limit=limit, raise_on_failure=raise_on_failure
+            )
+        )
 
     async def aread_sms(
         self,
         *,
         only_unread: bool | None = None,
         time_window: dt.timedelta | None = None,
         limit: int | None = None,
+        raise_on_failure: bool = False,
     ) -> ExecutionResult:
         if not self._has_any_persona_tool():
             raise ValueError(
@@ -507,16 +516,21 @@ async def aread_sms(
             payload["timedelta"] = time_window
         if limit is not None:
             payload["limit"] = limit
-        return await self.aexecute(**payload)
+        return await self.aexecute(raise_on_failure=raise_on_failure, **payload)
 
     def read_sms(
         self,
         *,
         only_unread: bool | None = None,
         time_window: dt.timedelta | None = None,
         limit: int | None = None,
+        raise_on_failure: bool = False,
     ) -> ExecutionResult:
-        return asyncio.run(self.aread_sms(only_unread=only_unread, time_window=time_window, limit=limit))
+        return asyncio.run(
+            self.aread_sms(
+                only_unread=only_unread, time_window=time_window, limit=limit, raise_on_failure=raise_on_failure
+            )
+        )
 
     async def locate(self, action: BaseAction) -> Locator | None:
         action_with_selector = await NodeResolutionPipe.forward(action, self._snapshot)
@@ -797,6 +811,9 @@ async def _aexecute_impl(
                             )
                         else:
                             success = await self.controller.execute(self.window, resolved_action, self._snapshot)
+                        if not success:
+                            # `message` still holds the success-phrased execution_message.
+                            message = f"Action '{resolved_action.type}' failed during browser execution"
 
             except (NoSnapshotObservedError, NoStorageObjectProvidedError, NoToolProvidedError) as e:
                 # this should be handled by the caller
@@ -854,6 +871,17 @@ async def _aexecute_impl(
             else:
                 resolved_action = step_action
 
+        if not success and exception is None:
+            # Actions that signal failure by returning (a tool returning `success=False`,
+            # a controller action returning `False`) carry no exception. Synthesize one
+            # before the result is built so the returned result, the trajectory and the
+            # raise below all agree on what failed.
+            exception = ActionExecutionError(
+                action_id=resolved_action.type,
+                url=self._window.page.url if self._window is not None else "",
+                reason=message or "unknown",
+            )
+
         execution_result = ExecutionResult(
             action=resolved_action,
             success=success,
@@ -873,6 +901,9 @@ async def _aexecute_impl(
                 logger.warning(f"Failed to capture post-action screenshot: {e}")
 
         _raise_on_failure = raise_on_failure if raise_on_failure is not None else self.default_raise_on_failure
+        # Gate on "did the action fail", not "did something throw": after the synthesis
+        # above, every failure carries an exception, including the return-style ones
+        # that were previously silently swallowed, the way evaluate_js was.
         if _raise_on_failure and exception is not None:
             raise exception
         return execution_result
@@ -881,8 +912,11 @@ def execute_saved_actions(self, actions_file: str) -> None:
         with open(actions_file, "r") as f:
             action_list = ActionList.model_validate_json(f.read())
         for i, action in enumerate(action_list.actions):
-            logger.info(f"💡 Step {i + 1}/{len(action_list.actions)}: executing action '{action.type}' {action.id}")
-            res = self.execute(action)
+            # browser-level actions (wait, goto, ...) have no `id` attribute
+            action_id = getattr(action, "id", "")
+            logger.info(f"💡 Step {i + 1}/{len(action_list.actions)}: executing action '{action.type}' {action_id}")
+            # replay stops gracefully on the first failed step instead of raising
+            res = self.execute(action, raise_on_failure=False)
             logger.info(f"{'✅' if res.success else '❌'} - {res.message}")
             if not res.success:
                 logger.error("🚨 Stopping execution of saved actions since last action failed...")

packages/notte-sdk/src/notte_sdk/client.py

@@ -227,7 +227,9 @@ def scrape(
             For image scraping: returns list[ImageData].
         """
         with self.Session(open_viewer=False, perception_type="fast") as session:
-            result = session.execute(GotoAction(url=url))
+            # best-effort navigation: scrape whatever loaded unless the goto
+            # actually threw server side
+            result = session.execute(GotoAction(url=url), raise_on_failure=False)
             if not result.success and result.exception is not None:
                 raise result.exception
             return session.scrape(raise_on_failure=raise_on_failure, **data)

packages/notte-sdk/src/notte_sdk/endpoints/sessions.py

@@ -81,13 +81,6 @@
 if TYPE_CHECKING:
     from notte_sdk.client import NotteClient
 
-_GENERIC_UNEXPECTED_MESSAGES: frozenset[str] = frozenset(
-    {
-        "An unexpected error occurred. Our team has been notified.",
-        "An unexpected error occurred.",
-    }
-)
-
 # Retry configuration constants
 CLUSTER_OVERLOAD_RETRY_DELAY = 30  # seconds to wait before retrying on 529 errors
 CONSOLE_VIEWER_URL = (
@@ -1587,19 +1580,19 @@ def execute(
         result = self.client.page.execute(session_id=self.session_id, action=action_obj)
         # raise exception if needed
         _raise_on_failure = raise_on_failure if raise_on_failure is not None else self.default_raise_on_failure
-        if _raise_on_failure and result.exception is not None:
+        # Gate on "did the action fail", not "did something throw", to mirror the local session.
+        if _raise_on_failure and not result.success:
             logger.error(f"🚨 Execution failed with message: '{result.message}'")
-            exception_to_raise: Exception = result.exception
-            if isinstance(exception_to_raise, NotteBaseError):
-                result_message = str(result.message).strip()
-                raised_message = str(exception_to_raise).strip()
-                if result_message and raised_message in _GENERIC_UNEXPECTED_MESSAGES:
-                    # Prefer the action-specific server message when the serialized exception
-                    # was reduced to a generic user-safe string.
-                    exception_to_raise = NotteBaseError(
-                        dev_message=result_message,
-                        user_message=result_message,
-                        agent_message=result_message,
-                    )
-            raise exception_to_raise from result.exception
+            if result.exception is not None:
+                # `ExecutionResult` validation rehydrated the concrete error type, messages
+                # and flags from the structured `exception_detail` wire payload.
+                raise result.exception
+            # An API build that predates `exception_detail` may report a failure without
+            # an exception; the message is all the caller has to go on.
+            fallback_message = str(result.message).strip() or f"Failed to execute action: {action_obj.type}"
+            raise NotteBaseError(
+                dev_message=fallback_message,
+                user_message=fallback_message,
+                agent_message=fallback_message,
+            )
         return result

packages/notte-sdk/src/notte_sdk/utils.py

@@ -147,14 +147,15 @@ def generate_cookies(session: RemoteSession, url: str, output_path: str) -> None
 
     form_fill_action = FormFillAction(value=dict(email=email, current_password=password))  # type: ignore
 
-    res = session.execute(form_fill_action)
+    # this helper has its own failure contract (ValueError / logged return)
+    res = session.execute(form_fill_action, raise_on_failure=False)
     if not res.success:
         logger.error(f"Failed to fill email & password: {res.message}")
         raise ValueError("Failed to fill email & password")
     logger.info("✅ Successfully filled email & password")
 
     actions = session.observe(instructions="Click on the 'Sign in' button", perception_type="deep")
-    res = session.execute(actions[0])
+    res = session.execute(actions[0], raise_on_failure=False)
     if not res.success:
         logger.error(f"Failed to click on the 'Sign in' button: {res.message}")
         return