Bitbucket Cache X Not Defined

A step's caches: list names a cache that is neither a built-in (like node, docker) nor declared under definitions: caches:. With no definition to bind to, the configuration is rejected.

What this error means

The pipeline fails configuration noting the named cache is not defined. Built-in cache names resolve automatically; any custom name must be declared first.

Configuration error: the cache "gradle" referenced in step "Build"
is not defined under definitions > caches.

Common causes

Custom cache referenced but never declared

A step caches: [ gradle ] needs a definitions: caches: gradle: <path> entry. Without it the name has no definition.

Typo or wrong built-in name

A misspelled name (nodes for node) or a custom name that does not match the definition key leaves the cache undefined.

How to fix it

Declare the custom cache under definitions

Add a definitions: caches: entry, then reference it by the same name.

definitions:
  caches:
    gradle: ~/.gradle/caches
pipelines:
  default:
    - step:
        caches: [ gradle ]
        script: [ ./gradlew build ]

Use exact built-in or defined names

1. For built-in caches, use the exact name (node, pip, docker).
2. For custom caches, match the step name to the definitions: caches: key.
3. Re-validate before pushing.

How to prevent it

• Declare every custom cache under definitions: caches: before use.
• Use exact built-in cache names.
• Keep cache names consistent between definition and step.

Related guides