cloudflare/cloudflared · error

checksum validation failed

Error message

checksum validation failed

What it means

During self-update, Apply() downloads the new binary and compares its SHA checksum against the checksum advertised by the update service. This error means the downloaded file's checksum did not match v.checksum, so the update is aborted as possibly corrupt or tampered.

Source

Thrown at cmd/cloudflared/updater/workers_update.go:99

// This includes signature and checksum validation,
// replacing the binary, etc
func (v *WorkersVersion) Apply() error {
	newFilePath := fmt.Sprintf("%s.new", v.targetPath)
	os.Remove(newFilePath) //remove any failed updates before download

	// download the file
	if err := download(v.downloadURL, newFilePath, v.isCompressed); err != nil {
		return err
	}

	downloadSum, err := cliutil.FileChecksum(newFilePath)
	if err != nil {
		return err
	}

	// Check that the file downloaded matches what is expected.
	if v.checksum != downloadSum {
		return errors.New("checksum validation failed")
	}

	// Check if the currently running version has the same checksum
	if downloadSum == buildInfo.Checksum {
		// Currently running binary matches the downloaded binary so we have no reason to update. This is
		// typically unexpected, as such we emit a sentry event.
		localHub := sentry.CurrentHub().Clone()
		err := errors.New("checksum validation matches currently running process")
		localHub.CaptureException(err)
		// Make sure to cleanup the new downloaded file since we aren't upgrading versions.
		os.Remove(newFilePath)
		return err
	}

	oldFilePath := fmt.Sprintf("%s.old", v.targetPath)
	// Windows requires more effort to self update, especially when it is running as a service:
	// you have to stop the service (if running as one) in order to move/rename the binary
	// but now the binary isn't running though, so an external process

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Retry the update; transient truncation is the most common cause
2. Bypass proxies/VPNs and download directly, or manually download the release and verify its checksum yourself
3. Reinstall cloudflared from the official release instead of self-update
4. Check egress filtering/SSL inspection appliances that rewrite binary responses

// verify checksum manually when self-update fails
sum := sha256.Sum256(data)
if hex.EncodeToString(sum[:]) != advertisedChecksum {
    return fmt.Errorf("download corrupted: got %s want %s", hex.EncodeToString(sum[:]), advertisedChecksum)
}

When it happens

Trigger: Truncated or corrupted download; an intermediary (proxy, captive portal, antivirus) modifying the response body; stale CDN cache serving a binary that no longer matches the advertised checksum.

Common situations: Flaky corporate networks stripping content; MITM proxies re-signing TLS; updating from behind a caching proxy with an old artifact.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• checksum validation matches currently running process
• v.Error

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