microsoft/autogen · error · ValueError

Cannot save screenshots without a debug directory. Set it us

Error message

Cannot save screenshots without a debug directory. Set it using the 'debug_dir' parameter. The debug directory is created if it does not exist.

What it means

MultimodalWebSurfer.__init__ raises ValueError when to_save_screenshots=True but debug_dir is None. Screenshots must be written somewhere, and the agent's contract is that the caller supplies the directory (created if missing) rather than the agent inventing a location. This fires immediately at construction time, before any browser is launched.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/agents/web_surfer/_multimodal_web_surfer.py:232

        description: str = DEFAULT_DESCRIPTION,
        debug_dir: str | None = None,
        headless: bool = True,
        start_page: str | None = DEFAULT_START_PAGE,
        animate_actions: bool = False,
        to_save_screenshots: bool = False,
        use_ocr: bool = False,
        browser_channel: str | None = None,
        browser_data_dir: str | None = None,
        to_resize_viewport: bool = True,
        playwright: Playwright | None = None,
        context: BrowserContext | None = None,
    ):
        """
        Initialize the MultimodalWebSurfer.
        """
        super().__init__(name, description)
        if debug_dir is None and to_save_screenshots:
            raise ValueError(
                "Cannot save screenshots without a debug directory. Set it using the 'debug_dir' parameter. The debug directory is created if it does not exist."
            )
        if model_client.model_info["function_calling"] is False:
            raise ValueError(
                "The model does not support function calling. MultimodalWebSurfer requires a model that supports function calling."
            )

        self._model_client = model_client
        self.headless = headless
        self.browser_channel = browser_channel
        self.browser_data_dir = browser_data_dir
        self.start_page = start_page or self.DEFAULT_START_PAGE
        self.downloads_folder = downloads_folder
        self.debug_dir = debug_dir
        self.to_save_screenshots = to_save_screenshots
        self.use_ocr = use_ocr
        self.to_resize_viewport = to_resize_viewport
        self.animate_actions = animate_actions

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Pass a debug directory: MultimodalWebSurfer(..., debug_dir='./debug', to_save_screenshots=True)
2. Or disable saving: leave to_save_screenshots=False (default) and omit debug_dir
3. Point debug_dir at a writable location; the constructor/agent creates it if missing

Example fix

// before
surfer = MultimodalWebSurfer(name='surfer', model_client=client, to_save_screenshots=True)

// after
surfer = MultimodalWebSurfer(name='surfer', model_client=client, debug_dir='./debug', to_save_screenshots=True)

def make_surfer(to_save_screenshots: bool, debug_dir: str | None = None, **kw):
    if to_save_screenshots and not debug_dir:
        raise ValueError('debug_dir is required when to_save_screenshots=True')
    ...

When it happens

Trigger: MultimodalWebSurfer(to_save_screenshots=True) with no debug_dir argument, or passing debug_dir=None explicitly while keeping screenshot saving enabled.

Common situations: Copying example code that sets to_save_screenshots=True for debugging, or enabling screenshots after a refactor that removed the debug_dir argument.

Related errors

• Unsupported config type {config.GetType()}
• The model does not support function calling. MultimodalWebSu
• No such element.
• Timeout must be greater than or equal to 1.
• endpoint is required for AzureAIChatCompletionClient

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/639fe6173a9ce5c0. Report an issue: GitHub.