CircleCI Cache Save/Restore Error Fix

In this tutorial, you'll learn about CircleCI Cache Save/Restore Error Fix. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Your CircleCI job reports Error saving cache or cache restore returns No cache found — the cache key doesn't match, the path is invalid, or the cache was evicted due to size limits.

The Problem

# WRONG — cache key that doesn't produce reusable matches
version: 2.1
jobs:
  build:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-deps-{{ .Branch }}-{{ .Revision }}
      - run: npm ci
      - save_cache:
          key: v1-deps-{{ .Branch }}-{{ .Revision }}
          paths:
            - node_modules

No cache found for keys:
  v1-deps-main-abc123def456

The cache key includes .Revision (the current commit SHA). Every commit has a unique SHA, so the cache is only valid for the exact same commit — effectively never reused.

Step-by-Step Fix

1. Use lock file hash for stable cache keys

steps:
  - restore_cache:
      keys:
        - v1-deps-{{ checksum "package-lock.json" }}
        - v1-deps-
  - run: npm ci
  - save_cache:
      key: v1-deps-{{ checksum "package-lock.json" }}
      paths:
        - node_modules

2. Use multiple restore keys for fallback

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

The first key is an exact match (best). The second falls back to any cache on the same branch. The third falls back to any cache from any branch.

3. Cache multiple dependency directories

steps:
  - restore_cache:
      keys:
        - v1-deps-{{ checksum "package-lock.json" }}-{{ checksum "Gemfile.lock" }}
  - run: |
      npm ci
      bundle install
  - save_cache:
      key: v1-deps-{{ checksum "package-lock.json" }}-{{ checksum "Gemfile.lock" }}
      paths:
        - node_modules
        - vendor/bundle
        - ~/.cache/yarn

4. Handle cache size limits

steps:
  - save_cache:
      key: v1-deps-{{ checksum "package-lock.json" }}
      paths:
        - node_modules

CircleCI caches up to 5GB per Repository. Set no_output_timeout: 30m for large installs. Use .circleci/config.yml to define cache policies.

Expected output:

Restoring cache from key: v1-deps-abc789...
Cache restored successfully
✓ npm ci completed (using cached node_modules)

Prevention Tips

• Use checksum of lock files for cache keys
• List fallback keys with broader prefixes
• Set different cache keys for different dependency managers
• Monitor cache usage in CircleCI Insights
• Clear caches from the UI when troubleshooting

Common Mistakes with cache error

1. Non-exhaustive pattern matches that compile with warnings then crash at runtime
2. Misunderstanding that String is [Char] with poor performance for large text operations
3. Using foldl instead of foldl' causing stack overflow on large lists

These mistakes appear frequently in real-world CIRCLECI code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ