GitHub Actions setup-* tool cache restore failed checksum

By Kaveh Alemi·Latchkey

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.

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

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

Let managed runners auto-retry

1. 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.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions