CloakHQ/CloakBrowser · error · RuntimeError

Pro binary unavailable: {e}. Your license is valid but the P

Error message

Pro binary unavailable: {e}. Your license is valid but the Pro binary could not be downloaded right now. Retry in a moment. To use the free binary instead, unset CLOAKBROWSER_LICENSE_KEY.

What it means

With a valid Pro license, if downloading the Pro binary fails transiently (network/HTTP error) and no cached Pro binary exists, ensure_binary raises RuntimeError instead of silently downgrading to the free binary.

Source

Thrown at cloakbrowser/download.py:232

                requested_version = None
            # A valid license is entitled to Pro, so Pro failures surface loudly
            # rather than silently substituting the older free binary. (A blip
            # during a routine update never reaches here: _ensure_pro_binary
            # returns the cached Pro binary and updates in the background.)
            try:
                return _ensure_pro_binary(
                    key,
                    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."

View on GitHub (pinned to d6bad5de26)

Solutions

Retry after a moment
Check network/firewall access to the Pro download endpoint
If Pro isn't required, unset CLOAKBROWSER_LICENSE_KEY to use the free binary

Example fix

# before/after shell
export CLOAKBROWSER_LICENSE_KEY=...  # fails during outage
unset CLOAKBROWSER_LICENSE_KEY         # free binary fallback

Defensive patterns

Strategy: retry

Try / catch

for attempt in range(3):
    try:
        path = ensure_binary()
        break
    except RuntimeError as e:
        if "Pro binary unavailable" in str(e) and attempt < 2:
            time.sleep(2 ** attempt); continue
        raise

Prevention

Run install once during CI image build to pre-cache the Pro binary
Monitor the download endpoint's availability for flakiness

When it happens

Trigger: CLOAKBROWSER_LICENSE_KEY set and validated, Pro download endpoint unreachable/erroring, no previously cached Pro build on disk; occurs in ensure_binary (launch, install).

Common situations: Server outage, flaky network, corporate firewall blocking the Pro CDN, first run on a new machine during an outage.

Related errors

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