quarkusio/quarkus · error · EnforcerRuleException

referenceArtifact must be in format 'groupId:artifactId:vers

Error message

referenceArtifact must be in format 'groupId:artifactId:version', got: ${referenceArtifact}

What it means

DependencyAlignmentRule parses referenceArtifact by splitting on ':' and requires exactly three parts: groupId, artifactId, version. If the configured value does not have exactly three colon-separated segments, execute() throws EnforcerRuleException showing the invalid value.

Source

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

        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);

        RepositorySystemSession repositorySession = session.getRepositorySession();

        // Get remote repositories directly from the project (no need for property evaluation)
        var remoteRepositories = project.getRemoteArtifactRepositories();

        // Get project's dependency versions
        Map<String, String> projectDependencyVersions = getProjectDependencyVersions(project);

        // Resolve the reference artifact
        Map<String, String> referenceDependencyVersions = resolveReferenceArtifact(

View on GitHub (pinned to e1c734241f)

Solutions

Set referenceArtifact to exactly 'groupId:artifactId:version', e.g. org.hibernate.orm:hibernate-platform:7.3.0.Final
Remove any extra ':packaging' or ':classifier' segments
Verify property placeholders resolve to a three-part GAV (mvn help:effective-pom)

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

// Shell: validate the GAV shape before configuring
echo "$GA" | grep -qE '^[^:]+:[^:]+:[^:]+$' && echo ok || echo "must be group:artifact:version"

Prevention

Always specify all three segments g:a:v; no packaging/classifier suffixes
Validate property values with a quick grep before wiring them into enforcer config
Use the exact example from the error message as a template

When it happens

Trigger: referenceArtifact set to a malformed string: only 'group:artifact' (version omitted), 'group:artifact:version:classifier' (extra segments), a bare artifact name, or a GAV using a different separator.

Common situations: Typing a BOM coordinates shorthand like 'org.hibernate.orm:hibernate-platform' without a version; pasting a full Maven coordinate with packaging/classifier; using an unresolved property inside the value.

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/d30740006fa1721a. Report an issue: GitHub.