quarkusio/quarkus · error · EnforcerRuleException

referenceArtifact must be configured (e.g., 'org.hibernate.o

Error message

referenceArtifact must be configured (e.g., 'org.hibernate.orm:hibernate-platform:7.3.0.Final')

What it means

DependencyAlignmentRule is a Maven enforcer rule that verifies versions of a set of artifacts against a single reference BOM/platform artifact. Before doing any work it validates its configuration; if the referenceArtifact string (the 'groupId:artifactId:version' to align against) is missing or blank, execute() throws EnforcerRuleException immediately.

Source

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

    @Inject
    private MavenSession session;

    @Inject
    private RepositorySystem repositorySystem;

    public void setReferenceArtifact(String referenceArtifact) {
        this.referenceArtifact = referenceArtifact;
    }

    public void setDependencies(List<DependencyAlignmentData> dependencies) {
        this.dependencies = dependencies;
    }

    @Override
    public void execute() throws EnforcerRuleException {
        // Validate configuration
        if (referenceArtifact == null || referenceArtifact.trim().isEmpty()) {
            throw new EnforcerRuleException(
                    "referenceArtifact must be configured (e.g., 'org.hibernate.orm:hibernate-platform:7.3.0.Final')");
        }
        if (dependencies == null || dependencies.isEmpty()) {
            getLog().warn("No dependencies configured for alignment check");
            return;
        }

        // Parse the reference artifact GAV
        String[] parts = referenceArtifact.split(":");
        if (parts.length != 3) {
            throw new EnforcerRuleException(
                    "referenceArtifact must be in format 'groupId:artifactId:version', got: " + referenceArtifact);
        }
        String referenceGroupId = parts[0];
        String referenceArtifactId = parts[1];
        String referenceVersion = parts[2];

        getLog().debug("Checking alignment with " + referenceArtifact);

View on GitHub (pinned to e1c734241f)

Solutions

Configure <referenceArtifact> in the rule's <configuration>, e.g. org.hibernate.orm:hibernate-platform:7.3.0.Final
If using a property placeholder, verify it is defined and non-empty in the effective pom (mvn help:effective-pom)
Ensure enforcer configuration is inside the correct <rules><dependencyAlignment> element, not misplaced

Example fix

// before
<referenceArtifact></referenceArtifact>
// after
<referenceArtifact>org.hibernate.orm:hibernate-platform:7.3.0.Final</referenceArtifact>

Defensive patterns

Strategy: validation

Validate before calling

<!-- Shell pre-check -->
mvn help:effective-pom | grep -A1 referenceArtifact
# Ensure a non-empty three-part GAV is configured

Prevention

Never add DependencyAlignmentRule without referenceArtifact; copy a working configuration from an existing pom
Use a property like ${hibernate.platform.version} and verify it is defined in the same pom or parent
Run mvn help:effective-pom to confirm placeholders resolve

When it happens

Trigger: Executing the rule (mvn enforcer:enforce on a pom where DependencyAlignmentRule is bound) with <referenceArtifact> omitted, set to empty string, or set to whitespace only in the rule configuration.

Common situations: Copy-pasting the rule into a pom without filling in referenceArtifact; property placeholders like ${hibernate.platform.version} resolving to empty because the property is undefined; accidental XML comment removal.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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