Struggling with ineffective ‘use cache’ directives in your CI/CD pipelines? This guide explains why your cache isn’t working and provides three practical, real-world solutions to fix it for good.

The Cache is a Lie: Why Your Build Script Ignores ‘use cache’ and How to Actually Fix It

I remember it like it was yesterday. A P1 hotfix for a major client was ready to go. The code was solid, the PR was approved, and all that was left was the final merge-to-main pipeline. It should have taken five minutes. Instead, we all watched in horror as the `npm install` step on `build-runner-03` ticked past the 15-minute mark. The cache, which we religiously configured to save our precious `node_modules` directory, was being completely ignored. A fifteen-minute build for a one-line CSS change. The project manager was pacing. The client was waiting. And I was staring at a log file, muttering, “But… we’re using the cache key. It should just work.” If you’re in DevOps, you’ve lived this moment. Let’s talk about why it happens and how to make sure it never happens to you again.

So, What’s Actually Happening? The Myth of the “Magic” Cache

When you’re starting out, it’s easy to see a `cache:` directive in a YAML file and think it’s a magic bullet. You tell it what to cache, and it just… does it. Right? Wrong. The runner isn’t just saving a folder; it’s saving a folder and associating it with a key. Think of it like a coat check ticket. When a new job starts, it looks at its ticket (the `key`) and asks the cache system, “Do you have anything for this exact ticket number?” If the ticket number doesn’t match perfectly, the system says “Nope, nothing here,” and your job has to go out and buy a whole new coat—by running `npm install` or `mvn clean install` from scratch.

The most common failure point isn’t the cache itself; it’s the key generation. If your key is too specific, too random, or based on the wrong files, you’ll get a “cache miss” every single time. The runner happily creates a new cache at the end of the job, but it’s for a ticket number that will never be used again.

Three Ways to Fix This Mess

Okay, enough theory. You’re here because your build is slow and you need a fix. Here are the three approaches I use, ranging from the quick-and-dirty to the architecturally sound.

1. The Quick Fix: “The Panic Button”

This is the “It’s 5 PM on a Friday and production is down” solution. In most CI/CD platforms (like GitLab CI or CircleCI), there’s a button in the UI, usually buried in the pipeline settings, labeled “Clear runner caches.”

When to use it: When you suspect a cache has become corrupted or a bad cache was saved with a key that is now blocking new, good caches from being created. It’s a blunt instrument. You’re not fixing the root cause, you’re just clearing the slate in the hope that the next run will behave. It’s a temporary fix that might get your urgent deployment out the door, but the problem will almost certainly come back.

2. The Permanent Fix: “The Right Key for the Job”

This is the real solution. You need to stop blaming the cache and start scrutinizing your key. The key should only change when the files you want to cache actually need to be regenerated.

For a Node.js project, when do you need to re-run `npm install`? When `package-lock.json` changes. Not when you change a README file. Not on every single commit.

Here’s a common bad pattern I see in `.gitlab-ci.yml` files:

# BAD - Don't do this!
cache:
  key: $CI_COMMIT_REF_SLUG
  paths:
    - node_modules/

The problem here is `$CI_COMMIT_REF_SLUG` changes for every branch. A feature branch won’t get to use the cache from the main branch, even if the dependencies are identical. A slightly better, but still flawed, approach is using `$CI_COMMIT_SHA`.

Here is the correct way to do it:

# GOOD - This is what you want
install_deps:
  stage: build
  script:
    - npm install
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/
    policy: pull-push

In this example, the CI system generates a hash of the `package-lock.json` file and uses that as the key. The cache is only invalidated and rebuilt when your dependencies actually change. This is efficient, logical, and how it was designed to be used.

Darian’s Pro Tip: Be mindful of your cache scope. Some systems allow you to create caches that are available project-wide, while others are locked to a specific branch. Using a file-based key like the one above makes your cache accessible across all branches, which is usually what you want. Faster feature branch builds for everyone!

3. The ‘Nuclear’ Option: “Fallback Keys”

Sometimes, you want the best of both worlds. You want a perfect match if it exists, but you’ll take a “close enough” match if it doesn’t. This is where fallback keys (supported in some platforms like GitHub Actions) come in handy. It’s a more advanced technique but can save you from a full, slow dependency install.

The idea is to provide an ordered list of keys. The runner tries the first key (the most specific one). If it gets a miss, it tries the second, and so on. This allows you to restore a slightly older cache and let the package manager figure out the small differences, which is still much faster than starting from zero.

# GITHUB ACTIONS EXAMPLE
- name: Cache node modules
  id: cache-npm
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: npm-deps-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-deps-

Here, it first looks for a cache with a key matching the exact `package-lock.json` hash. If it can’t find one, it will restore the most recent cache that simply starts with `npm-deps-`. It’s a great strategy to ensure you almost always have *some* kind of cache to start with.

Comparing The Solutions

At the end of the day, a CI/CD cache is a tool, not a magic wand. Take the time to understand how its keying mechanism works. That “boring” documentation you skipped might just save you from a 15-minute panic during your next critical deployment. Trust me, your blood pressure will thank you.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions