browser-use/browser-use · warning · RuntimeError

Failed to initialize video recorder — ensure optional deps a

Error message

Failed to initialize video recorder — ensure optional deps are installed (`pip install "browser-use[video]"`).

What it means

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.

Source

Thrown at browser_use/browser/watchdogs/recording_watchdog.py:78

		"""
		if self._recorder is not None:
			raise RuntimeError(f'Recording already in progress (output: {self._recorder.output_path})')

		if size is None:
			self.logger.debug('record size not specified, detecting viewport size...')
			size = await self._get_current_viewport_size()
		if not size:
			raise RuntimeError('Cannot start video recording: viewport size could not be determined.')

		if framerate is None:
			framerate = self.browser_session.browser_profile.record_video_framerate

		output_path = Path(output_path)
		self.logger.debug(f'Initializing video recorder → {output_path}')
		recorder = VideoRecorderService(output_path=output_path, size=size, framerate=framerate)
		recorder.start()
		if not recorder._is_active:
			raise RuntimeError(
				'Failed to initialize video recorder — ensure optional deps are installed (`pip install "browser-use[video]"`).'
			)

		self._recorder = recorder
		self.browser_session.cdp_client.register.Page.screencastFrame(self.on_screencastFrame)
		self._screencast_params = {
			'format': 'png',
			'quality': 90,
			'maxWidth': size['width'],
			'maxHeight': size['height'],
			'everyNthFrame': 1,
		}
		await self._start_screencast()
		return output_path

	async def stop_recording(self) -> Path | None:
		"""
		Stop any in-progress recording and finalize the output file.

View on GitHub (pinned to 6c73fced2f)

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

Example fix

# before
browser = Browser()  # no video extra installed

# after
# pip install "browser-use[video]"
browser = Browser(
    record_video_dir='./recordings',
)

Defensive patterns

Strategy: try-catch

Validate before calling

def can_record_video() -> bool:
    try:
        import browser_use.browser.video_recorder  # noqa: F401
        return True
    except Exception:
        return False

if not can_record_video():
    print('Install browser-use[video] to enable recording')

Try / catch

try:
    await watchdog.start_recording(output_path)
except RuntimeError as e:
    logger.warning(f'Video recording unavailable: {e}')  # degrade gracefully, continue session

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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