Gradle "Timeout waiting to lock" - Fix Cache Lock Contention in CI

Gradle could not acquire a lock on one of its caches within the timeout. Either a previous build crashed and left a stale lock file, or two Gradle processes are competing for the same Gradle user home at once.

What this error means

The build hangs, then fails with Timeout waiting to lock <cache>. It is currently in use by another Gradle instance. and often an owner PID. Re-running after the stale process is gone, or isolating the home, fixes it.

gradle output

* What went wrong:
Timeout waiting to lock artifact cache
(/root/.gradle/caches/modules-2). It is currently in use by another Gradle
instance.
Owner PID: 1234
Our PID: 5678

Common causes

Stale lock from a crashed/killed build

A build that was SIGKILLed or OOM-killed never released its cache lock. The next build waits, then times out trying to acquire it.

Concurrent Gradle processes sharing one home

Two jobs (or matrix legs) on the same runner sharing ~/.gradle contend for the same lock, and one times out.

How to fix it

Give each job its own Gradle user home

Isolate the Gradle user home so concurrent builds do not contend for one lock.

.github/workflows/ci.yml

export GRADLE_USER_HOME="$RUNNER_TEMP/gradle-${{ github.run_id }}-${{ strategy.job-index }}"
./gradlew --no-daemon build

Clear a stale lock from a dead process

If no Gradle is actually running, remove the leftover lock and rebuild.

Terminal

pkill -f gradle || true
rm -f ~/.gradle/caches/**/*.lock
./gradlew --no-daemon build

How to prevent it

Use a per-job GRADLE_USER_HOME for parallel/matrix builds on shared runners.
Run --no-daemon in CI so no long-lived daemon holds locks.
Avoid persisting cache locks across runs.