GitHub Actions setup-* tool cache restore failed checksum

setup-* actions verify downloaded toolchains against an expected checksum. A mismatch means the download was corrupted or truncated - usually a transient network failure during the fetch.

What this error means

A setup-node/python/go step fails with a checksum or hash mismatch while restoring the tool.

github-actions

Error: Checksum mismatch for downloaded tool.
Expected sha256 abc123... but got def456...
The tool cache restore failed checksum verification.

Common causes

Corrupted or truncated download

A transient network failure delivered an incomplete archive that fails verification.

Stale poisoned tool cache

A previously cached bad copy on a self-hosted runner fails verification.

How to fix it

Re-run to re-download

Re-run the job; a fresh download usually passes verification.
On self-hosted runners, clear the tool cache directory if a poisoned copy persists.

Let managed runners auto-retry

Latchkey auto-retries transient toolchain download/checksum failures from warm pools, so a single corrupted fetch does not fail the build.

How to prevent it

Treat isolated checksum failures as transient and retry.
Keep self-hosted tool caches clean.

Related guides

GitHub Actions "has encountered an internal error" (retry)Handle "GitHub Actions has encountered an internal error while running your job" - a transient server-side fa… GitHub Actions "Failed to download action" (rate limited)Fix "Failed to download action" caused by rate limiting when the runner fetches an action archive. GitHub Actions setup-node/setup-python Cache Not Restoring DependenciesFix setup-node / setup-python built-in caching that never restores - a missing lockfile, wrong cache-dependen…