quarkusio/quarkus · error · EnforcerRuleException

Dependency version alignment check failed: ${errors}

Error message

Dependency version alignment check failed:
${errors}

What it means

After comparing each configured dependency's actual version against the version declared by the reference artifact, DependencyAlignmentRule collects all mismatches into an errors list and, if any exist, throws EnforcerRuleException with the full report. This is the rule's primary purpose: failing the build when managed versions drift from the platform/BOM.

Source

Thrown at independent-projects/enforcer-rules/src/main/java/io/quarkus/enforcer/DependencyAlignmentRule.java:135

                } else {
                    getLog().debug("Artifact '%s' not found in project (skipping)".formatted(artifact));
                }
                continue;
            }

            if (!expectedVersion.equals(actualVersion)) {
                errors.append("""
                          - Version mismatch for '%s':
                            Project declares version '%s'
                            but reference artifact expects '%s'
                        """.formatted(artifact, actualVersion, expectedVersion));
            } else {
                getLog().debug("✓ %s version %s is aligned".formatted(artifact, actualVersion));
            }
        }

        if (!errors.isEmpty()) {
            throw new EnforcerRuleException("Dependency version alignment check failed:\n" + errors);
        }
    }

    /**
     * Extracts dependency versions from the project's dependencyManagement and dependencies sections.
     *
     * @param project the Maven project
     * @return a map of "groupId:artifactId" to version
     */
    private Map<String, String> getProjectDependencyVersions(MavenProject project) {
        Map<String, String> versions = new HashMap<>();

        // First, check dependencyManagement section
        if (project.getDependencyManagement() != null
                && project.getDependencyManagement().getDependencies() != null) {
            project.getDependencyManagement().getDependencies().forEach(dep -> {
                String key = dep.getGroupId() + ":" + dep.getArtifactId();
                if (dep.getVersion() != null) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Align the reported dependency versions to the reference artifact's versions (remove explicit version overrides so dependencyManagement wins)
2. If the newer version is intentional, update the reference platform artifact to a version that includes it
3. If the mismatch is acceptable, remove that artifact from the rule's <dependencies> configuration or use the rule's skip/exclude options
4. Run mvn enforcer:enforce -X to see per-artifact debug output of expected vs actual versions

Example fix

// before: version drifts from platform
<dependency><groupId>org.hibernate.orm</groupId><artifactId>hibernate-core</artifactId><version>7.3.1.Final</version></dependency>
// after: aligned via platform dependencyManagement
<dependency><groupId>org.hibernate.orm</groupId><artifactId>hibernate-core</artifactId></dependency>

# Compare managed versions against the platform before enforcing
mvn dependency:tree -Dverbose | grep -E '(version managed from|omitted for conflict)'
mvn dependency:list | grep -E 'hibernate|aligned-artifact'

// Enforcer fails the build with the report; process it in CI
if (!mvnVerify()) {
    def mismatches = parseEnforcerReport("target/enforcer-report")
    mismatches.each { alignVersion(it.artifact, it.expectedVersion) }
}

When it happens

Trigger: mvn enforcer:enforce runs while one or more configured <dependencies> have a version that differs from the version resolved in the reference artifact's dependencyManagement (e.g. a module overrides hibernate-core 7.3.1 while the platform pins 7.3.0.Final).

Common situations: A module pins a newer patch to get a bugfix; a dependency management import overrides the platform; a merge updated one version but not its aligned siblings; automation bumped versions inconsistently.

Related errors

• ${coords} is missing version and is not found among the depe
• ${illegalRuntimeGAVs.size()} illegal runtime dependencies fo
• referenceArtifact must be configured (e.g., 'org.hibernate.o
• referenceArtifact must be in format 'groupId:artifactId:vers
• Failed to resolve reference artifact ${groupId}:${artifactId

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/11d6512cb4ce80da. Report an issue: GitHub.