Bitbucket Cloud · Pipelines · Checked October 29, 2026

Bitbucket Pipelines: the cache is not used

You added caches to bitbucket-pipelines.yml, and every build still downloads everything. Bitbucket saves a cache only under a few conditions, and says why it did not in the step's log. Look there first, then match the cause below.

Where to look

The repository's Pipelines page, button Caches near the top right, between Schedules and Usage: the caches Bitbucket has. If yours is not listed, it was never saved.
The step that should have saved it: expand Build teardown at the end of its log. It says when a cache was not uploaded because the step failed, was empty or was over the size limit.

Seven reasons a cache is not used

From Atlassian's article (Pipeline build cache-related issues) and its caches page:

No step has succeeded since you added it. A cache is saved only after a successful step. A failed step uploads nothing.
It is over 1 GB once compressed. Larger caches are not saved. Split the directory into two or more caches.
It is empty. Your tool installs somewhere other than the path you gave. Add ls -lah <cache-directory> after the install command to see what is there, and point the cache at the real directory.
It expired. Caches are kept for a week; the next successful step saves a new one.
It is static and your dependencies changed. A cache defined as a plain path, or one of the pre-defined caches, is neither used nor updated when the dependencies change. For the Docker cache, a changed Dockerfile does the same: the layers no longer match. Clear it from Caches, or use a file-based key (below).
It is the Docker cache and the step runs on Runtime v3. The pre-defined Docker cache is deprecated there; the teardown says "Docker cache upload is not supported in this environment". Use Docker buildx caches instead.
It is the Docker cache on the older runtime, where a known bug (BCLOUD-23193) means it is not used consistently. Until it is fixed, Atlassian suggests Runtime v3 for the step, with buildx caches.

Two more limits from the caches page: a parallel step can read caches but not write them, and a cache can be cleared at any time, so a build must work without it.

The pre-defined caches and what they hold

Name	Directory
`node`	`node_modules`
`composer`	`~/.composer/cache`
`maven`	`~/.m2/repository`
`gradle`	`~/.gradle/caches`
`pip`	`~/.cache/pip`
`dotnetcore`	`~/.nuget/packages`
`ivy2`	`~/.ivy2/cache`
`docker`	`/var/lib/docker`

A tool not in the list, or one that installs elsewhere, needs its own cache under definitions, for example ~/.npm or ~/.cache/Cypress.

A cache that follows your lock file

With a file-based key, Pipelines makes a new version of the cache when the files change, so old dependencies are not reused:

definitions:
  caches:
    npm-deps:
      key:
        files:
          - package-lock.json
      path: node_modules

pipelines:
  default:
    - step:
        caches:
          - npm-deps
        script:
          - npm ci
          - npm test

To start over by hand, rename the cache (npm-deps-v2) or clear it from the Caches button.

See what each build costs, from IntelliJ IDEA

Pipeline Inbox for Bitbucket Pipelines, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the pipelines of all your Bitbucket Cloud repositories in an IDE tool window, with each step's duration, the pipeline's build minutes, and the step's log, teardown included, so you can see whether a cache was saved and whether the next build got faster. The list, steps and logs are free; running, re-running and stopping pipelines are Pro (US$1.50 a month, with a 30-day trial).

Get it on JetBrains Marketplace

Atlassian, Bitbucket and Bitbucket Pipelines are trademarks of Atlassian; Docker is a trademark of Docker, Inc.; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by Atlassian, Docker or JetBrains.

More: Pipelines did not run after a push · "Exceeded build time limit of 120 minutes" · "Container 'Build' exceeded memory limit." · "Container 'docker' exceeded memory limit." · "unexpected system error" · "command not found" · Submodules not cloned · "We couldn't clone the repository" · "No online runner available" · "No space left on device" · "Step exceeded processing limits" · The artifact is missing in the next step · The build passed before and fails now · Build setup takes too long · "You've run out of build minutes" · "Permission denied to update branch" · "You have reached your pull rate limit" (Docker Hub) · "There is an error in your bitbucket-pipelines.yml" · "This pipeline was paused" (deployments) · Bitbucket Pipelines plugins for IntelliJ IDEA, compared · 日本語