NanmiCoder/MediaCrawler · critical · RuntimeError

No available browser found. Please ensure Chrome or Edge bro

Error message

No available browser found. Please ensure Chrome or Edge browser is installed, or set CUSTOM_BROWSER_PATH in config file to specify browser path.

What it means

Raised by CDPBrowserManager._get_browser_path() when no Chrome/Edge executable is found: config.CUSTOM_BROWSER_PATH is unset or does not exist as a file, and launcher.detect_browser_paths() returns an empty list for all known install locations. The crawler cannot launch a browser to drive.

Source

Thrown at tools/cdp_browser.py:212

        utils.logger.info("[CDPBrowserManager] Successfully connected to existing browser")
        return browser_context

    async def _get_browser_path(self) -> str:
        """
        Get browser path
        """
        # Prefer user-defined path
        if config.CUSTOM_BROWSER_PATH and os.path.isfile(config.CUSTOM_BROWSER_PATH):
            utils.logger.info(
                f"[CDPBrowserManager] Using custom browser path: {config.CUSTOM_BROWSER_PATH}"
            )
            return config.CUSTOM_BROWSER_PATH

        # Auto-detect browser path
        browser_paths = self.launcher.detect_browser_paths()

        if not browser_paths:
            raise RuntimeError(
                "No available browser found. Please ensure Chrome or Edge browser is installed, "
                "or set CUSTOM_BROWSER_PATH in config file to specify browser path."
            )

        browser_path = browser_paths[0]  # Use the first browser found
        browser_name, browser_version = self.launcher.get_browser_info(browser_path)

        utils.logger.info(
            f"[CDPBrowserManager] Detected browser: {browser_name} ({browser_version})"
        )
        utils.logger.info(f"[CDPBrowserManager] Browser path: {browser_path}")

        return browser_path

    async def _test_cdp_connection(self, debug_port: int) -> bool:
        """
        Test if CDP connection is available
        """

View on GitHub (pinned to d6f7c5bb90)

Solutions

Install Google Chrome or Microsoft Edge on the host
Or set CUSTOM_BROWSER_PATH in config to the exact binary path (verify with `which google-chrome` / `ls`)
In Docker, install chromium and point CUSTOM_BROWSER_PATH at it (e.g. /usr/bin/chromium)
os.path.isfile is strict: ensure the path is the executable file itself, not its directory, and is readable

Example fix

# before
CUSTOM_BROWSER_PATH = ""  # and no system Chrome installed

# after (Docker example)
apt-get install -y chromium
# config/base_config.py
CUSTOM_BROWSER_PATH = "/usr/bin/chromium"

Defensive patterns

Strategy: validation

Validate before calling

import os, shutil

def browser_binary_available() -> bool:
    if config.CUSTOM_BROWSER_PATH:
        return os.path.isfile(config.CUSTOM_BROWSER_PATH)
    return bool(shutil.which("google-chrome") or shutil.which("chromium") or shutil.which("microsoft-edge"))

if not browser_binary_available():
    raise SystemExit("install Chrome/Edge or set CUSTOM_BROWSER_PATH to the binary")

Type guard

def has_browser_path() -> bool:
    custom = getattr(config, "CUSTOM_BROWSER_PATH", "")
    return (bool(custom) and os.path.isfile(custom)) or bool(shutil.which("google-chrome")) or bool(shutil.which("chromium"))

Try / catch

try:
    path = await mgr._get_browser_path()
except RuntimeError as e:
    raise SystemExit(
        f"{e}\nFix: apt-get install -y chromium (or install Chrome) "
        "then set CUSTOM_BROWSER_PATH=/usr/bin/chromium"
    ) from e

Prevention

Bake Chrome/Chromium into Docker images used for crawling
Set CUSTOM_BROWSER_PATH to the binary file (verify with `which`), not a directory
Add an environment preflight that checks for a browser before a long crawl

When it happens

Trigger: Running on a machine with no Chrome/Edge installed (typical minimal Docker/alpine images, CI runners, headless servers); CUSTOM_BROWSER_PATH pointing to a wrong or non-existent path; Chromium installed under an unrecognized name/location so detection misses it.

Common situations: Docker deployments that never install a browser; macOS/Windows paths changed by channel (Chrome Beta/Canary only); CUSTOM_BROWSER_PATH set to a directory instead of the binary; Playwright-bundled chromium present but not detected because only Chrome/Edge paths are scanned.

Related errors

AI-assisted analysis of NanmiCoder/MediaCrawler@d6f7c5bb90 (2026-08-15). Data as JSON: /api/errors/9ba2ca48705f5729. Report an issue: GitHub.