Gradle build fails when dependency resolution would update lockfile

No version of Gradle supports automatic lockfile regeneration during a standard build. The --write-locks flag is the only supported mechanism to update lockfiles; there is no configuration property or setting to enable automatic updates.

Behavioral Explanation

Dependency locking is designed specifically to prevent the "silent" updates that occur with dynamic versions (e.g., 1.+) or changing snapshots. If Gradle detects that the current resolution result differs from the recorded entries in the lockfile, it intentionally fails the build. This failure serves as a guardrail, ensuring that developers and CI environments use identical dependency graphs until a human explicitly decides to update them.

Confirmed Facts

• Consistency: This behavior has remained consistent from the feature's introduction in Gradle 5.0 through the current stable releases.
• Enforcement: When a mismatch occurs, Gradle throws a build failure explicitly instructing the user to use --write-locks.
• Scope: This applies to all configurations where locking is enabled.

Required Steps for Updating Locks

To resolve a build failure caused by a lockfile mismatch, follow these steps:

1. Regenerate the lockfile: Run the build or the specific resolution task with the write flag:

   ./gradlew build --write-locks

2. Verify the changes: Inspect the generated gradle.lockfile (or configuration-specific lockfiles) using your version control system to ensure the version jumps are expected.
3. Commit the lockfile: Commit the updated lockfile to your repository so that other team members and the CI pipeline receive the same resolved versions.

Verification

You can verify this behavior by adding a dynamic dependency to your build.gradle:

dependencies {
    implementation 'org.apache.commons:commons-lang3:+'
}

Once a lockfile is created, any new release of commons-lang3 will cause subsequent ./gradlew build commands to fail until --write-locks is applied again.

Diagnostic Detail: Are you using a custom Gradle plugin that manages dependencies? Some third-party plugins may attempt to wrap resolution logic, which could mask or alter standard locking errors.