Caching Error on macOS

When restoring a cache on a macOS job, you may run into 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

This error is commonly caused by trying to extract a cache that has been created on a Docker or Machine job. It is not advisable to share caches between different executor types as features such as symlinks or permissions metadata can differ and cause issues.

Solution

To work around this, use a cache key that includes the platform you are running the job on. For example:

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

Can become:

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

This "arch" key includes the OS and CPU architecture information which will ensure the cache is unique to that particular combination in use on the executor.