{"record":{"id":"639fe6173a9ce5c0","repo":"microsoft/autogen","slug":"cannot-save-screenshots-without-a-debug-directory","errorCode":null,"errorMessage":"Cannot save screenshots without a debug directory. Set it using the 'debug_dir' parameter. The debug directory is created if it does not exist.","messagePattern":"Cannot save screenshots without a debug directory\\. Set it using the 'debug_dir' parameter\\. The debug directory is created if it does not exist\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/agents/web_surfer/_multimodal_web_surfer.py","lineNumber":232,"sourceCode":"        description: str = DEFAULT_DESCRIPTION,\n        debug_dir: str | None = None,\n        headless: bool = True,\n        start_page: str | None = DEFAULT_START_PAGE,\n        animate_actions: bool = False,\n        to_save_screenshots: bool = False,\n        use_ocr: bool = False,\n        browser_channel: str | None = None,\n        browser_data_dir: str | None = None,\n        to_resize_viewport: bool = True,\n        playwright: Playwright | None = None,\n        context: BrowserContext | None = None,\n    ):\n        \"\"\"\n        Initialize the MultimodalWebSurfer.\n        \"\"\"\n        super().__init__(name, description)\n        if debug_dir is None and to_save_screenshots:\n            raise ValueError(\n                \"Cannot save screenshots without a debug directory. Set it using the 'debug_dir' parameter. The debug directory is created if it does not exist.\"\n            )\n        if model_client.model_info[\"function_calling\"] is False:\n            raise ValueError(\n                \"The model does not support function calling. MultimodalWebSurfer requires a model that supports function calling.\"\n            )\n\n        self._model_client = model_client\n        self.headless = headless\n        self.browser_channel = browser_channel\n        self.browser_data_dir = browser_data_dir\n        self.start_page = start_page or self.DEFAULT_START_PAGE\n        self.downloads_folder = downloads_folder\n        self.debug_dir = debug_dir\n        self.to_save_screenshots = to_save_screenshots\n        self.use_ocr = use_ocr\n        self.to_resize_viewport = to_resize_viewport\n        self.animate_actions = animate_actions","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/agents/web_surfer/_multimodal_web_surfer.py#L214-L250","documentation":"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.","triggerScenarios":"MultimodalWebSurfer(to_save_screenshots=True) with no debug_dir argument, or passing debug_dir=None explicitly while keeping screenshot saving enabled.","commonSituations":"Copying example code that sets to_save_screenshots=True for debugging, or enabling screenshots after a refactor that removed the debug_dir argument.","solutions":["Pass a debug directory: MultimodalWebSurfer(..., debug_dir='./debug', to_save_screenshots=True)","Or disable saving: leave to_save_screenshots=False (default) and omit debug_dir","Point debug_dir at a writable location; the constructor/agent creates it if missing"],"exampleFix":"// before\nsurfer = MultimodalWebSurfer(name='surfer', model_client=client, to_save_screenshots=True)\n\n// after\nsurfer = MultimodalWebSurfer(name='surfer', model_client=client, debug_dir='./debug', to_save_screenshots=True)","handlingStrategy":"validation","validationCode":"def make_surfer(to_save_screenshots: bool, debug_dir: str | None = None, **kw):\n    if to_save_screenshots and not debug_dir:\n        raise ValueError('debug_dir is required when to_save_screenshots=True')\n    ...","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pair to_save_screenshots=True with debug_dir in one config object","Default to_save_screenshots to False in shared constructors","Construct the surfer inside a factory that validates both flags together"],"tags":["configuration","web-surfer","constructor","playwright"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}