cloudflare/cloudflared · error · Exception

failed to get checksums: {0}

Error message

failed to get checksums: {0}

What it means

kv_get_keys raises this when the Cloudflare Workers KV list-keys API returns a non-200 status code with at least one error entry in the JSON body. The exception carries the first API error object from the response. Note the message is formatted incorrectly: Exception('failed to get checksums: {0}', errors[0]) passes the placeholder literally and errors[0] becomes the exception's second argument, so the logged message never contains the actual error details.

Source

Thrown at github_message.py:35

GITHUB_CONFLICT_CODE = "already_exists"
BASE_KV_URL = 'https://api.cloudflare.com/client/v4/accounts/'


def kv_get_keys(prefix, account, namespace, api_token):
    """ get the KV keys for a given prefix """
    response = requests.get(
        BASE_KV_URL + account + "/storage/kv/namespaces/" +
        namespace + "/keys" + "?prefix=" + prefix,
        headers={
            "Content-Type": "application/json",
            "Authorization": "Bearer " + api_token,
        },
    )
    if response.status_code != 200:
        jsonResponse = response.json()
        errors = jsonResponse["errors"]
        if len(errors) > 0:
            raise Exception("failed to get checksums: {0}", errors[0])
    return response.json()["result"]


def kv_get_value(key, account, namespace, api_token):
    """ get the KV value for a provided key """
    response = requests.get(
        BASE_KV_URL + account + "/storage/kv/namespaces/" + namespace + "/values/" + key,
        headers={
            "Content-Type": "application/json",
            "Authorization": "Bearer " + api_token,
        },
    )
    if response.status_code != 200:
        jsonResponse = response.json()
        errors = jsonResponse["errors"]
        if len(errors) > 0:
            raise Exception("failed to get checksums: {0}", errors[0])
    return response.text

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Inspect the raised exception's args[1] (the first API error object) to identify the actual Cloudflare error code and message.
2. Verify the API token is valid and has Workers KV read permissions for the namespace.
3. Confirm account id and namespace_id are correct and the namespace still exists.
4. Fix the exception formatting to use str.format or an f-string so the real error text is in the message.

Example fix

// before
raise Exception("failed to get checksums: {0}", errors[0])
// after
raise Exception("failed to get checksums: {0}".format(errors[0]))

def kv_get_keys(account, namespace, api_token):
    if not api_token or not account or not namespace:
        raise ValueError("account, namespace and api_token are required")
    resp = requests.get(url, headers={"Authorization": f"Bearer {api_token}"}, timeout=30)
    if resp.status_code == 401 or resp.status_code == 403:
        raise PermissionError("KV token invalid or lacks permissions")
    resp.raise_for_status()

try:
    keys = kv_get_keys(account, namespace, token)
except Exception as e:
    api_err = e.args[1] if len(e.args) > 1 else e
    logging.error("KV list failed: %s", api_err)
    sys.exit(1)

When it happens

Trigger: Calling kv_get_keys when the Cloudflare API responds with HTTP != 200 and a non-empty errors array — e.g. invalid/expired api_token, wrong account id or namespace_id, wrong base URL, or KV API downtime.

Common situations: CI release jobs where the KV_API_TOKEN secret is missing or rotated, a namespace_id pointing to a deleted namespace, or an account_id mismatch (token scoped to another account).

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• failed to upload checksum: {0}
• ErrUnauthorized
• ErrBadRequest
• ErrAPINoSuccess
• Failed to fetch page. Server returned: %d

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/88ce5ed8be5cdfa0. Report an issue: GitHub.