CloakHQ/CloakBrowser · error · FileNotFoundError

CLOAKBROWSER_BINARY_PATH set to '{local_override}' but file

Error message

CLOAKBROWSER_BINARY_PATH set to '{local_override}' but file does not exist

What it means

ensure_binary honors the CLOAKBROWSER_BINARY_PATH override first; if the env var is set but the path does not exist on disk, it raises FileNotFoundError immediately rather than falling back to downloading.

Source

Thrown at cloakbrowser/download.py:187

    release_channel: str | None = None,
) -> str:
    """Ensure the stealth Chromium binary is available. Download if needed.

    Returns the path to the chrome executable as a string.

    Args:
        license_key: Pro license key. Also reads from CLOAKBROWSER_LICENSE_KEY env var.
        browser_version: Exact Chromium version pin. Also reads from CLOAKBROWSER_VERSION.
        release_channel: Stable (default) or Preview binary channel.

    Set CLOAKBROWSER_BINARY_PATH to skip download and use a local build.
    """
    # Check for local override first
    local_override = get_local_binary_override()
    if local_override:
        path = Path(local_override)
        if not path.exists():
            raise FileNotFoundError(
                f"CLOAKBROWSER_BINARY_PATH set to '{local_override}' but file does not exist"
            )
        logger.info("Using local binary override: %s", local_override)
        return str(path)

    requested_version = normalize_requested_version(browser_version)

    # Pro license key check (custom download URL overrides Pro path)
    from .license import (
        CloakBrowserLicenseError,
        resolve_license_key,
        validate_license,
    )

    key = resolve_license_key(license_key)
    if os.environ.get("CLOAKBROWSER_DOWNLOAD_URL"):
        key = None

View on GitHub (pinned to d6bad5de26)

Solutions

1. Fix the path to point at an existing executable
2. Unset CLOAKBROWSER_BINARY_PATH to let cloakbrowser download/manage the binary
3. Verify with ls -l "$CLOAKBROWSER_BINARY_PATH"

Example fix

# before
CLOAKBROWSER_BINARY_PATH=/opt/old/chrome ./run.sh
# after
unset CLOAKBROWSER_BINARY_PATH && ./run.sh

import os
from pathlib import Path

def binary_override_ok() -> bool:
    p = os.environ.get("CLOAKBROWSER_BINARY_PATH")
    return p is None or (Path(p).exists() and os.access(p, os.X_OK))

def env_binary_valid() -> bool:
    import os
    p = os.environ.get("CLOAKBROWSER_BINARY_PATH", "")
    return p == "" or os.path.isfile(p)

try:
    ensure_binary()
except FileNotFoundError as e:
    if "CLOAKBROWSER_BINARY_PATH" in str(e):
        os.environ.pop("CLOAKBROWSER_BINARY_PATH", None)
        ensure_binary()
    else:
        raise

When it happens

Trigger: Setting CLOAKBROWSER_BINARY_PATH to a stale, moved, or typo'd path, then calling ensure_binary/launch/cmd_install.

Common situations: Binary was deleted or the project moved; container rebuild lost the file; typo or wrong home dir in the path; CI env var carried over from another machine.

Related errors

• [cloakbrowser] CLOAKBROWSER_WIDEVINE_CDM is set but has no m

AI-assisted analysis of CloakHQ/CloakBrowser@d6bad5de26 (2026-08-28). Data as JSON: /api/errors/fdfa03ec7779d00e. Report an issue: GitHub.