unclecode/crawl4ai · error · RuntimeError

Browser executable not found for type: {browser_type}

Error message

Browser executable not found for type: {browser_type}

What it means

RuntimeError raised when Playwright reports an empty executable_path for a valid browser type. The name passed validation, but the browser binaries are not installed in this environment, so Playwright cannot resolve an executable and crawl4ai refuses to cache an empty path.

Source

Thrown at crawl4ai/utils.py:680

    from playwright.async_api import async_playwright
    async with async_playwright() as p:
        browsers = {
            'chromium': p.chromium,
            'firefox': p.firefox, 
            'webkit': p.webkit
        }
        
        if browser_type.lower() not in browsers:
            raise ValueError(
                f"Invalid browser type. Must be one of: {', '.join(browsers.keys())}"
            )
            
        # Save the path int the crawl4ai home folder
        home_folder = get_home_folder()
        browser_path = browsers[browser_type.lower()].executable_path
        if not browser_path:
            raise RuntimeError(f"Browser executable not found for type: {browser_type}")
        # Save the path in a text file with browser type name
        with open(os.path.join(home_folder, f"{browser_type.lower()}.path"), "w") as f:
            f.write(browser_path)
        
        return browser_path

def beautify_html(escaped_html):
    """
    Beautifies an escaped HTML string.

    Parameters:
    escaped_html (str): A string containing escaped HTML.

    Returns:
    str: A beautifully formatted HTML string.
    """
    # Unescape the HTML string
    unescaped_html = html.unescape(escaped_html)

View on GitHub (pinned to 7e80152142)

Solutions

1. Install the browsers: playwright install (or playwright install chromium for just one), or run crawl4ai-setup.
2. Check PLAYWRIGHT_BROWSERS_PATH: unset it or point it at the directory that actually contains the browser builds.
3. In Docker, do the install in the image build step, not at runtime.
4. Delete any stale <browser>.path cache file in the crawl4ai home folder (~/.crawl4ai) if a previous bad run wrote one, then retry.

Example fix

# before
path = await get_browser_executable_path("chromium")  # RuntimeError: Browser executable not found for type: chromium

# after (shell)
# playwright install chromium   # or: crawl4ai-setup
path = await get_browser_executable_path("chromium")

import subprocess, shutil, os

def browser_installed(browser: str = "chromium") -> bool:
    cache = os.path.expanduser("~/.cache/ms-playwright")
    return any(browser in d for d in os.listdir(cache)) if os.path.isdir(cache) else False

# if not browser_installed(): subprocess.run(["playwright", "install", browser], check=True)

try:
    path = await get_browser_executable_path("chromium")
except RuntimeError as e:
    if 'Browser executable not found' in str(e):
        subprocess.run(["playwright", "install", "chromium"], check=True)
        path = await get_browser_executable_path("chromium")

When it happens

Trigger: Calling get_browser_executable_path('chromium'|'firefox'|'webkit') on a machine where `playwright install` was never run (or the browsers were removed), or where PLAYWRIGHT_BROWSERS_PATH points somewhere empty.

Common situations: Fresh clones, CI images, and slim Docker containers that pip-installed crawl4ai/playwright but skipped browser download; PLAYWRIGHT_BROWSERS_PATH env var pointing to a stale or wrong directory; partial installs interrupted midway.

Related errors

• Invalid browser type. Must be one of: {', '.join(browsers.ke
• Failed to start browser: {e}
• Unsupported browser type: {browser_type}
• C4A script compiler not available. Please ensure crawl4ai.sc
• Failed on navigating ACS-GOTO: {str(e)}

AI-assisted analysis of unclecode/crawl4ai@7e80152142 (2026-08-14). Data as JSON: /api/errors/d46cc37b5a6af40b. Report an issue: GitHub.