Troubleshooting Cache Not Found During Restore

Problem

When running your CircleCI build, you see "No cache is found" during the restore_cache step, but the save_cache step shows the cache already exists. This happens when the cache key used to save the cache differs from the key used to restore it.

Solutions

Verify Checksum Files Are Unchanged

The most common cause is a modified lock file between the restore and save steps. If your cache key includes a checksum (for example, {{ checksum "Gemfile.lock" }}), any changes to that file will create a different cache key.

Check if any installation steps modify your lock file:

Review your configuration for commands that update dependencies
Look for version mismatches between your local development environment and CircleCI
Ensure lock files are committed to version control

Ruby Bundler: Check for Version Mismatches

If you use Ruby Bundler and have different Bundler versions between local and CircleCI environments, the bundle install step may overwrite your Gemfile.lock file. This creates a new checksum and changes the cache key.

To fix this:

Verify that both environments use the same Bundler version
Commit the Gemfile.lock file to your repository
Consider using bundle install --frozen to prevent lock file modifications

Review Cache Key Templates

Examine your cache key configuration for dynamic values that may change unexpectedly:

restore_cache:
  keys:
    - v1-deps-{{ .Branch }}-{{ checksum "package-lock.json" }}
    - v1-deps-{{ .Branch }}-
    - v1-deps-

Ensure the checksum file exists and remains unchanged between restore and save steps.

Verify Cache Age and Retention

Check your cache age and retention settings to make sure they haven't aged out.

Cache retention settings can be changed:

At an organization level on the plans page
At a job level through configuration, which will override the organization default

If either of these is particularly short, your cache may have expired.

Outcome

After applying these solutions, your restore_cache step should successfully find and restore the cache. You can verify this by checking the build output, which should show the cache being restored with a matching key.

If the cache still cannot be found, the fallback keys (less specific keys in your keys list) will restore a partial cache, and your dependency installation will download only new or updated dependencies.

Additional Notes

Cache keys have a 900-character limit
Caches are immutable once written - you cannot overwrite an existing cache
Multiple jobs in a workflow may create race conditions when writing to the same cache key
The default cache storage duration is 15 days

Additional Resources