Panniantong/Agent-Reach · error · RuntimeError

Cookie extraction{profile_hint} requires browser_cookie3 (or

Error message

Cookie extraction{profile_hint} requires browser_cookie3 (or rookiepy when no profile is selected).
Install: pip install browser-cookie3

What it means

Raised by extract_all() in agent_reach/cookie_extract.py when neither rookiepy nor browser_cookie3 can be imported. rookiepy is only attempted when no profile is selected (rookiepy cannot target a specific profile folder); otherwise the code needs browser_cookie3, and if that import fails the extraction cannot proceed.

Source

Thrown at agent_reach/cookie_extract.py:256

    # Try rookiepy first (Rust-based, more stable), fallback to browser_cookie3
    use_rookiepy = False
    if cookie_file is None:
        try:
            import rookiepy
            use_rookiepy = True
        except ImportError:
            pass
    if not use_rookiepy:
        try:
            import browser_cookie3
        except ImportError:
            profile_hint = (
                f" for profile '{scrub_url_credentials(profile)}'"
                if profile is not None
                else ""
            )
            raise RuntimeError(
                f"Cookie extraction{profile_hint} requires browser_cookie3"
                " (or rookiepy when no profile is selected).\n"
                "Install: pip install browser-cookie3"
            )

    if use_rookiepy:
        # rookiepy returns list of dicts with name/value/domain/path keys
        try:
            browser_funcs = {
                "chrome": rookiepy.chrome,
                "firefox": rookiepy.firefox,
                "edge": rookiepy.edge,
                "brave": rookiepy.brave,
                "opera": rookiepy.opera,
            }
            raw_cookies = browser_funcs[browser](list(spec["domains"]))
            # Wrap into objects with .name, .value, .domain for compatibility
            class _Cookie:

View on GitHub (pinned to 93ae1d18c3)

Solutions

pip install browser-cookie3 (covers both the profile and no-profile paths)
If you do not need a profile, ensure rookiepy is installed so the rookiepy path is used
Verify with `python -c "import browser_cookie3"` inside the same venv agent-reach runs in

Example fix

# before: ModuleNotFoundError leads to RuntimeError at extract time
extract_all(browser='chrome', platform='bilibili', profile='Profile 1')

# after
pip install browser-cookie3
extract_all(browser='chrome', platform='bilibili', profile='Profile 1')

Defensive patterns

Strategy: validation

Validate before calling

def cookie_backend_available(profile: str | None) -> bool:
    if profile is None:
        try:
            import rookiepy; return True
        except ImportError:
            pass
    try:
        import browser_cookie3; return True
    except ImportError:
        return False

Type guard

def can_extract(profile: str | None) -> bool:
    return cookie_backend_available(profile)

Try / catch

try:
    extract_all(browser=b, platform=p, profile=prof)
except RuntimeError as e:
    if 'browser_cookie3' in str(e):
        subprocess.run([sys.executable, '-m', 'pip', 'install', 'browser-cookie3'])
    else:
        raise

Prevention

Ship browser-cookie3 in your deployment requirements when profiles are used
Check importability in doctor/startup diagnostics before extraction
Remember rookiepy cannot serve explicit profile= requests

When it happens

Trigger: Calling extract_all() on a machine where neither package is installed, or extract_all(profile='Profile 1') where only rookiepy (at most) is available — the profile path forces browser_cookie3.

Common situations: Fresh install of agent-reach without the optional cookie extras; venv missing browser-cookie3; using profile= in an environment that only installed rookiepy.

Related errors

AI-assisted analysis of Panniantong/Agent-Reach@93ae1d18c3 (2026-08-14). Data as JSON: /api/errors/da73de4bcf3f3462. Report an issue: GitHub.