"Error untarring cache" when running a macOS job

Issue

When restoring a cache on a macOS job, you may encounter the following error:

Downloading cache archive...
Validating cache...

Unarchiving cache...

Failed to unarchive cache

Error untarring cache: Error extracting tarball /var/... : home/circleci/project/...: Cannot extract through symlink

Cause

This error typically occurs when attempting to extract a cache that was created on a Docker or Machine job. Sharing caches across different executor types is not recommended, as differences in features such as symlinks and permissions metadata can lead to extraction failures.

Solution

To avoid this issue, ensure that your cache key includes the platform on which the job is running. This ensures that caches are only used within compatible environments.

Example Fix

Instead of using a cache key like this:

node-v1-{{ .Branch }}-{{ checksum "package-lock.json" }}

Modify it to include the OS and CPU architecture:

node-v1-{{ arch }}-{{ .Branch }}-{{ checksum "package-lock.json" }}

Why This Works

The {{ arch }} key automatically includes OS and CPU architecture details, ensuring that caches are uniquely associated with their respective environments. This prevents conflicts when restoring caches across different executor types.

By implementing this fix, you can prevent cache extraction errors and maintain reliable builds across multiple environments.

Resources

https://circleci.com/docs/caching/#using-keys-and-templates