CloakHQ/CloakBrowser · error · RuntimeError

GeoIP resolution failed: could not determine {missing joined

Error message

GeoIP resolution failed: could not determine {missing joined by ' and '}

What it means

When geoip=True (or GeoIP resolution runs), cloakbrowser resolves your exit IP's timezone and locale. If neither the caller nor the GeoIP lookup produced a timezone and/or locale, maybe_resolve_geoip raises RuntimeError listing the missing fields, because Playwright fingerprint consistency requires both values.

Source

Thrown at cloakbrowser/browser.py:1332

    # None when no proxy → echo services resolve the machine's own public IP
    proxy_url = _extract_proxy_url(proxy) if proxy else None

    # When both tz/locale are explicit, resolve the exit IP for WebRTC — but only
    # with a proxy. With no proxy the WebRTC IP would just be the real connection
    # IP the site already sees (a no-op), so skip the third-party echo call.
    if timezone is not None and locale is not None:
        exit_ip = resolve_proxy_exit_ip(proxy_url) if proxy_url else None
        return timezone, locale, exit_ip

    geo_tz, geo_locale, exit_ip = resolve_proxy_geo_with_ip(proxy_url)
    if timezone is None:
        timezone = geo_tz
    if locale is None:
        locale = geo_locale
    missing = [name for name, value in (("timezone", timezone), ("locale", locale)) if value is None]
    if missing:
        raise RuntimeError(
            "GeoIP resolution failed: could not determine " + " and ".join(missing)
        )
    return timezone, locale, exit_ip


def _resolve_webrtc_args(
    args: list[str] | None,
    proxy: str | ProxySettings | None,
) -> list[str] | None:
    """Replace --fingerprint-webrtc-ip=auto with the resolved proxy exit IP.

    Returns args unchanged if no ``auto`` value is present.
    """
    if not args:
        return args
    idx = None
    for i, a in enumerate(args):
        if a == "--fingerprint-webrtc-ip=auto":

View on GitHub (pinned to d6bad5de26)

Solutions

Pass explicit timezone= and locale= matching your proxy's geography
Verify the GeoIP service is reachable and the exit IP is a real routable IP
Retry with a different proxy exit IP that has GeoIP data

Example fix

# before
browser = cloakbrowser.launch(geoip=True)
# after
browser = cloakbrowser.launch(geoip=True, timezone="America/New_York", locale="en-US")

Defensive patterns

Strategy: validation

Validate before calling

from cloakbrowser.browser import maybe_resolve_geoip
import inspect
# ensure explicit timezone/locale before launching with geoip
tz = my_tz or "America/New_York"
loc = my_locale or "en-US"

Try / catch

try:
    browser = cloakbrowser.launch(geoip=True)
except RuntimeError as e:
    if "GeoIP resolution failed" in str(e):
        browser = cloakbrowser.launch(geoip=True, timezone=tz, locale=loc)
    else:
        raise

Prevention

Always pass timezone/locale explicitly when using proxies with geoip
Test with your production exit IP before deploying

When it happens

Trigger: Calling launch(..., geoip=True) (or geoip_enabled config) without explicit timezone/locale while the GeoIP service returns no timezone or locale data for the exit IP, e.g. an unresolvable datacenter/VPN IP.

Common situations: VPN/proxy exit IPs that GeoIP databases can't map; GeoIP API outage; corporate proxies with exotic egress IPs.

Related errors

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