Self-Healing CI: Clearing a Corrupted Dependency Cache and Retrying

When a build breaks on a corrupted cache, the cache is the problem, not your code - clearing it and rebuilding from a clean state fixes it every time.

The problem

A build fails with a checksum mismatch, an unexpected-EOF on an archive, or a "cache entry is corrupt" error. The dependencies are fine; a cache entry was written partially or got corrupted. A human clears the cache and re-runs, and the build passes unchanged.

error: failed to extract ... unexpected end of archive
# or
warning: checksum mismatch for cached artifact; cache may be corrupt

Why it happens

Caches are restored from archives that can be truncated or corrupted if a previous job was interrupted mid-write, or if storage returned a partial object. Restoring a damaged entry then fails extraction or integrity checks downstream.

The failure is mechanical and self-correcting: discarding the bad entry and rebuilding the cache from the source of truth resolves it without touching your code.

The manual fix

The manual fix is to evict the bad cache and rebuild it:

1. Delete or invalidate the corrupted cache entry (e.g. bump the cache key).
2. Re-run the job so the cache is repopulated from a clean install.
3. Verify the next run restores a valid cache before relying on it again.

How this gets automated

A corrupt-cache failure has a recognizable integrity-error signature, and the remedy is deterministic: discard the bad entry and rebuild from source. A self-healing CI pipeline detects the corruption, evicts the affected cache, retries the step so the cache is rebuilt cleanly, and only escalates if the failure recurs against a fresh cache - which would point to a real upstream problem.

Related guides