{"record":{"id":"207ed66ff79f8d81","repo":"browser-use/browser-use","slug":"failed-to-initialize-video-recorder-ensure-optio","errorCode":null,"errorMessage":"Failed to initialize video recorder — ensure optional deps are installed (`pip install \"browser-use[video]\"`).","messagePattern":"Failed to initialize video recorder — ensure optional deps are installed \\(`pip install \"browser-use\\[video\\]\"`\\)\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"warning","filePath":"browser_use/browser/watchdogs/recording_watchdog.py","lineNumber":78,"sourceCode":"\t\t\"\"\"\n\t\tif self._recorder is not None:\n\t\t\traise RuntimeError(f'Recording already in progress (output: {self._recorder.output_path})')\n\n\t\tif size is None:\n\t\t\tself.logger.debug('record size not specified, detecting viewport size...')\n\t\t\tsize = await self._get_current_viewport_size()\n\t\tif not size:\n\t\t\traise RuntimeError('Cannot start video recording: viewport size could not be determined.')\n\n\t\tif framerate is None:\n\t\t\tframerate = self.browser_session.browser_profile.record_video_framerate\n\n\t\toutput_path = Path(output_path)\n\t\tself.logger.debug(f'Initializing video recorder → {output_path}')\n\t\trecorder = VideoRecorderService(output_path=output_path, size=size, framerate=framerate)\n\t\trecorder.start()\n\t\tif not recorder._is_active:\n\t\t\traise RuntimeError(\n\t\t\t\t'Failed to initialize video recorder — ensure optional deps are installed (`pip install \"browser-use[video]\"`).'\n\t\t\t)\n\n\t\tself._recorder = recorder\n\t\tself.browser_session.cdp_client.register.Page.screencastFrame(self.on_screencastFrame)\n\t\tself._screencast_params = {\n\t\t\t'format': 'png',\n\t\t\t'quality': 90,\n\t\t\t'maxWidth': size['width'],\n\t\t\t'maxHeight': size['height'],\n\t\t\t'everyNthFrame': 1,\n\t\t}\n\t\tawait self._start_screencast()\n\t\treturn output_path\n\n\tasync def stop_recording(self) -> Path | None:\n\t\t\"\"\"\n\t\tStop any in-progress recording and finalize the output file.","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/browser-use/browser-use/blob/6c73fced2f6d45a11d88622fe56365a5fe18f28b/browser_use/browser/watchdogs/recording_watchdog.py#L60-L96","documentation":"Raised by RecordingWatchdog.start_recording after it constructs a VideoRecorderService, calls recorder.start(), and the recorder never becomes active. The most common cause is that the optional video-encoding dependencies (the browser-use[video] extra) are not installed, so the encoder thread/process cannot start. Note that the watchdog itself degrades gracefully on BrowserConnectedEvent (logs 'Skipping video recording'), so an uncaught raise means you called start_recording() directly.","triggerScenarios":"Setting record_video_dir on the browser profile (or calling (await browser_session.get_watchdog_or_similar) start_recording(output_path)) in an environment where imageio-ffmpeg/av or whatever the video extra provides is missing, so VideoRecorderService.start() fails silently and _is_active stays False.","commonSituations":"Installing plain `pip install browser-use` instead of `pip install \"browser-use[video]\"`; a Docker/CI image built without the extra; a venv recreated after a dependency prune; recording works locally but fails in headless production containers.","solutions":["Install the optional extra: pip install \"browser-use[video]\" (or uv pip install \"browser-use[video]\")","Verify in the failing environment: python -c \"import browser_use.browser.video_recorder\" and check that the encoder dependency imports cleanly","If deps are present, check that the output directory (record_video_dir) exists and is writable, and that the viewport size passed to start_recording is non-empty","Rebuild your Docker/CI image with the [video] extra so it does not regress"],"exampleFix":"# before\nbrowser = Browser()  # no video extra installed\n\n# after\n# pip install \"browser-use[video]\"\nbrowser = Browser(\n    record_video_dir='./recordings',\n)","handlingStrategy":"try-catch","validationCode":"def can_record_video() -> bool:\n    try:\n        import browser_use.browser.video_recorder  # noqa: F401\n        return True\n    except Exception:\n        return False\n\nif not can_record_video():\n    print('Install browser-use[video] to enable recording')","typeGuard":null,"tryCatchPattern":"try:\n    await watchdog.start_recording(output_path)\nexcept RuntimeError as e:\n    logger.warning(f'Video recording unavailable: {e}')  # degrade gracefully, continue session","preventionTips":["Install browser-use[video] in every environment that sets record_video_dir","Include the extra in requirements.txt/Dockerfile explicitly","Smoke-test recorder startup in CI for recording-enabled deployments"],"tags":["video","optional-dependencies","watchdog","recording"],"backgroundTag":null,"analyzedSha":"6c73fced2f6d45a11d88622fe56365a5fe18f28b","analyzedAt":"2026-08-14T19:42:40.557Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}