cloudflare/cloudflared · error · Exception

failed to upload checksum: {0}

Error message

failed to upload checksum: {0}

What it means

send_hash raises this when the HTTP request used to store the asset checksum in Workers KV returns a status code other than 200 with at least one error entry in the JSON body. The exception carries the first API error object, though — like its siblings — the '{0}' placeholder is never interpolated, so the message stays literal and the details sit in args[1].

Source

Thrown at github_release.py:53

def send_hash(pkg_hash, name, version, account, namespace, api_token):
    """ send the checksum of a file to workers kv """
    key = '{0}_{1}_{2}'.format(UPDATER_PREFIX, version, name)
    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer " + api_token,
    }
    response = requests.put(
            BASE_KV_URL + account + "/storage/kv/namespaces/" + namespace + "/values/" + key,
            headers=headers,
            data=pkg_hash
    )

    if response.status_code != 200:
        jsonResponse = response.json()
        errors = jsonResponse["errors"]
        if len(errors) > 0:
            raise Exception("failed to upload checksum: {0}", errors[0])



def assert_tag_exists(repo, version):
    """ Raise exception if repo does not contain a tag matching version """
    tags = repo.get_tags()
    if not tags or tags[0].name != version:
        raise Exception("Tag {} not found".format(version))


def get_or_create_release(repo, version, dry_run=False, is_draft=False):
    """
    Get a Github Release matching the version tag or create a new one.
    If a conflict occurs on creation, attempt to fetch the Release on last time
    """
    try:
        release = repo.get_release(version)
        logging.info("Release %s found", version)

View on GitHub (pinned to 2253eeeb25)

Solutions

  1. Inspect the exception's args[1] for the actual Cloudflare error code/message.
  2. Verify the api_token has Workers KV Edit permission on the target namespace.
  3. Confirm account_id and namespace_id match the existing namespace.
  4. Fix the exception formatting to interpolate errors[0] into the message.

Example fix

// before
raise Exception("failed to upload checksum: {0}", errors[0])
// after
raise Exception("failed to upload checksum: {}".format(errors[0]))
Defensive patterns

Strategy: try-catch

Validate before calling

if not kv_api_token or not kv_account_id or not namespace_id:
    raise ValueError("KV credentials (token, account, namespace) must be set before upload")

Try / catch

try:
    send_hash(kv, key, sha)
except Exception as e:
    logging.error("checksum upload failed: %s", e.args[1] if len(e.args) > 1 else e)
    raise SystemExit(1)

Prevention

When it happens

Trigger: Uploading a release asset whose checksum KV PUT/POST call fails: invalid KV api_token, wrong account_id or namespace_id, KV write permissions missing on the token, or the Cloudflare API being unavailable/rate-limited.

Common situations: CI publish jobs where the KV namespace was recreated (new namespace_id) or the token's scope was narrowed, causing authenticated-but-forbidden writes during github-release uploads.

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

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