GitHub Actions actions/cache "tar exited with 2" on restore

By Daniel Zoghalchali·Latchkey

actions/cache stores the cached paths in a tar archive and extracts it on restore. A corrupted archive, an absolute/relative path mismatch, or a different tar (BSD vs GNU on Windows/macOS) can make extraction exit non-zero.

What this error means

A cache restore step fails during extraction with tar reporting exit code 2, sometimes after a partial upload or a cross-OS cache reuse.

/usr/bin/tar: ...: Cannot open: No such file or directory
/usr/bin/tar: Exiting with failure status due to previous errors
Warning: Tar failed with error: tar exited with error code 2

Common causes

Corrupt or partially uploaded archive

A cache saved from an interrupted run can be incomplete, so extraction hits missing entries.

Cross-OS or tar-implementation mismatch

Reusing a cache key across Linux/Windows/macOS, or differing tar builds, can break path handling during extract.

How to fix it

Scope keys per OS and bust corrupt caches

1. Include runner.os in the cache key so archives are not shared across OSes.
2. Bump the key prefix to invalidate a corrupt cache entry.
3. Restrict path to directories that exist on the runner.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}

How to prevent it

• Always namespace cache keys with runner.os.
• Bump a key version segment when archive contents change shape.
• Latchkey managed runners auto-retry transient cache restore/extract failures instead of failing the job on a one-off tar error.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions