CloakHQ/CloakBrowser · error · CloakBrowserLicenseError

CloakBrowser Pro: license could not be validated (server unr

Error message

CloakBrowser Pro: license could not be validated (server unreachable and no cached validation). Retry in a moment, or unset CLOAKBROWSER_LICENSE_KEY to use the free binary.

What it means

A license key was supplied but it could not be validated because the license server is unreachable and no cached validation exists. cloakbrowser fails closed rather than guessing, but tells you how to fall back to the free binary.

Source

Thrown at cloakbrowser/download.py:247

            except Exception as e:
                # Transient failure with no cached Pro binary to use — surface a
                # clear error rather than silently downloading the free binary.
                raise RuntimeError(
                    f"Pro binary unavailable: {e}. Your license is valid but the "
                    f"Pro binary could not be downloaded right now. Retry in a "
                    f"moment. To use the free binary instead, unset "
                    f"CLOAKBROWSER_LICENSE_KEY."
                ) from e
        elif info:
            # Key supplied but rejected — abort, never downgrade to free.
            raise CloakBrowserLicenseError(
                f"CloakBrowser Pro: license key is invalid or expired "
                f"(plan={info.plan}). Check CLOAKBROWSER_LICENSE_KEY, or unset it "
                f"to use the free binary."
            )
        else:
            # Key supplied but unvalidatable (server down, no cache) — abort.
            raise CloakBrowserLicenseError(
                "CloakBrowser Pro: license could not be validated (server "
                "unreachable and no cached validation). Retry in a moment, or "
                "unset CLOAKBROWSER_LICENSE_KEY to use the free binary."
            )

    # Fail fast if no binary available for this platform
    check_platform_available()

    if requested_version:
        binary_path = get_binary_path(requested_version)
        if binary_path.exists() and _is_executable(binary_path):
            logger.debug(
                "Pinned binary found in cache: %s (version %s)",
                binary_path,
                requested_version,
            )
            _show_welcome()
            return str(binary_path)

View on GitHub (pinned to d6bad5de26)

Solutions

Retry when the server is reachable
Open network access to the license endpoint
Unset CLOAKBROWSER_LICENSE_KEY to use the free binary

Defensive patterns

Strategy: fallback

Try / catch

from cloakbrowser.download import CloakBrowserLicenseError
try:
    ensure_binary()
except CloakBrowserLicenseError as e:
    if "could not be validated" in str(e):
        os.environ.pop("CLOAKBROWSER_LICENSE_KEY", None)
        ensure_binary()  # free binary fallback
    else:
        raise

Prevention

Pre-validate the license while online (run install in the image build)
Allow a config flag to gracefully degrade to the free binary

When it happens

Trigger: CLOAKBROWSER_LICENSE_KEY set, license server unreachable/timeout, and no cached validation on this machine (e.g. first run offline).

Common situations: CI with restricted egress; offline development; DNS/firewall blocking the license API.

Related errors

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