ConfigCat "Config JSON ... failed to fetch" in CI

The ConfigCat SDK tried to download its config JSON from the CDN and the request failed or returned an unexpected status. The key may be valid but the runner cannot reach cdn-global.configcat.com, or a proxy blocked the request. The client then serves defaults or the last cached config.

What this error means

ConfigCat logs "Unexpected HTTP response was received while trying to fetch config JSON" or "Request timed out while trying to fetch config JSON". Setting evaluations return defaults.

ConfigCat - ERROR - [1103] Unexpected HTTP response was received while trying to
fetch config JSON: 502 Bad Gateway

Common causes

The runner cannot reach the ConfigCat CDN

Egress to cdn-global.configcat.com is blocked or times out, so the config JSON never downloads.

A proxy returns an unexpected status

An intercepting proxy answers with 502 or 403 instead of the config, so the SDK cannot parse a valid response.

How to fix it

Allow egress or route through the proxy

1. Allow the runner to reach the ConfigCat CDN host on 443.
2. If a proxy is required, configure the SDK proxy options.
3. Retry to confirm whether the failure is transient.

client = configcatclient.get(
    os.environ["CONFIGCAT_SDK_KEY"],
    ConfigCatOptions(proxies={"https": "http://proxy.internal:8080"}),
)

Use flag overrides for offline tests

Feed values from a local file so tests evaluate deterministically without reaching the CDN.

ConfigCatOptions(
    flag_overrides=LocalFileFlagOverrides(
        file_path="flags.json", override_behaviour=OverrideBehaviour.LOCAL_ONLY,
    ),
)

How to prevent it

• Allowlist the ConfigCat CDN host on CI networks.
• Configure proxy settings on the SDK where a proxy is mandatory.
• Use local flag overrides in tests to remove the network dependency.

Related guides