Bitbucket "definitions" Custom Cache Path Invalid or Empty

You declared a custom cache under definitions: caches:, but the path it points at does not exist (or is empty) when the step finishes - so nothing is ever stored and every run is a cold miss.

What this error means

A step lists a custom cache, the log notes the cache was created but stays tiny, and the next run still installs from scratch. The cache "works" structurally but never carries real content forward.

Cache "gradle" created (0 B).
# next run:
Cache "gradle" not found.

Common causes

The cache path does not exist in the container

A custom cache pointed at ~/.gradle only works if Gradle actually writes there. If the tool uses a different home (e.g. GRADLE_USER_HOME is set elsewhere), the declared path is empty and saves nothing.

Path is relative or outside the clone

Custom cache paths are resolved against a known base. A relative path that points at the wrong directory, or one outside the build container’s writable area, captures no files.

How to fix it

Point the cache at the real tool directory

Define the cache at the exact path the tool writes to, and reference it from the step.

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

Confirm where the tool actually caches

1. Run the build once and ls -la the directory you expect to cache.
2. If the tool respects an env var (e.g. GRADLE_USER_HOME), set it and cache that exact path.
3. Check the end of the step log for a non-trivial cache size, proving content was stored.

How to prevent it

• Verify the cached directory has files before relying on it.
• Pin tool home directories with env vars so the path is stable.
• Keep reusable cache paths in definitions: caches: rather than ad hoc per step.

Related guides