CloakHQ/CloakBrowser · error · CloakBrowserLicenseError

CloakBrowser Pro: license key is invalid or expired (plan={i

Error message

CloakBrowser Pro: license key is invalid or expired (plan={info.plan}). Check CLOAKBROWSER_LICENSE_KEY, or unset it to use the free binary.

What it means

A CLOAKBROWSER_LICENSE_KEY was supplied and the license server explicitly rejected it (invalid or expired, with a returned plan). The library aborts and never silently downgrades to the free binary.

Source

Thrown at cloakbrowser/download.py:240

                    requested_version=requested_version,
                    plan=info.plan,
                    release_channel=release_channel,
                )
            except BinaryVerificationError:
                # Authenticity could not be confirmed — surface verbatim.
                raise
            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):

View on GitHub (pinned to d6bad5de26)

Solutions

Renew or correct CLOAKBROWSER_LICENSE_KEY
Remove surrounding whitespace/quotes from the env var
Unset CLOAKBROWSER_LICENSE_KEY if the free binary is acceptable

Defensive patterns

Strategy: try-catch

Try / catch

from cloakbrowser.download import CloakBrowserLicenseError
try:
    ensure_binary()
except CloakBrowserLicenseError as e:
    if "invalid or expired" in str(e):
        alert_ops_license_expired()
    raise

Prevention

Validate the license key at deploy time in a health check
Keep license renewals automated to avoid expired-key surprises

When it happens

Trigger: Expired subscription, revoked key, typo'd key in CLOAKBROWSER_LICENSE_KEY; raised during ensure_binary on any launch or install.

Common situations: Trial expired; key rotated; copy-paste whitespace in the env var; using an old key after plan cancellation.

Related errors

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