Bitbucket "Cache not found" - Cache Miss in Pipelines

By Daniel Zoghalchali·Latchkey

Bitbucket reported it could not find a cache to restore. On a first run or after the cache key changes this is normal; if it never restores, the cache path or key is wrong.

What this error means

The step log shows "Cache <name> not found" and proceeds without a restored cache, so installs/builds run from scratch. The build still succeeds but is slower than expected.

Cache "node" not found. The cache will be created after this step.

Common causes

Cold cache or changed key

The first run, or any run after the cache key inputs change, has nothing to restore. Bitbucket creates the cache at the end of the step instead.

Wrong cache path or unsaved cache

A custom cache pointed at a path that does not exist, or a step that fails before the cache is saved, means there is never a cache to restore later.

How to fix it

Declare caches correctly

Use a predefined cache like node, or define a custom cache with a real path.

definitions:
  caches:
    npm: ~/.npm
pipelines:
  default:
    - step:
        caches: [ node, npm ]
        script: [ npm ci, npm test ]

Confirm the cache is being saved

1. Check the end of the step log for a "cache saved" line.
2. Ensure the cached path exists after install (e.g. ~/.npm).
3. Remember the cache only saves on a successful step - fix earlier failures first.

How to prevent it

• Point custom caches at paths that actually exist after install.
• Expect a miss on the first run and after dependency changes.
• Keep cache definitions in definitions: caches: for reuse.

Frequently asked questions

Related guides

References

• GitHub Actions documentation