quarkusio/quarkus · error · EnforcerRuleException

Failed to resolve reference artifact ${groupId}:${artifactId

Error message

Failed to resolve reference artifact ${groupId}:${artifactId}:${version}

What it means

DependencyAlignmentRule resolves the configured reference artifact through Maven's ArtifactDescriptorReader to extract its managed dependency versions. If resolution fails (artifact not in any configured repository, corrupted local cache, wrong coordinates), ArtifactDescriptorException is caught and rethrown as EnforcerRuleException 'Failed to resolve reference artifact g:a:v'.

Source

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

            var deps = descriptorResult.getDependencies();
            if (deps != null) {
                var dependenciesAdded = (int) deps.stream()
                        .map(org.eclipse.aether.graph.Dependency::getArtifact)
                        .filter(a -> a.getVersion() != null && !a.getVersion().isEmpty())
                        .filter(a -> !versions.containsKey(a.getGroupId() + ":" + a.getArtifactId()))
                        .peek(a -> versions.put(a.getGroupId() + ":" + a.getArtifactId(), a.getVersion()))
                        .count();
                if (dependenciesAdded > 0) {
                    getLog().debug("Extracted %d additional dependencies from dependencies section"
                            .formatted(dependenciesAdded));
                }
            }

            getLog().debug("Total: %d dependencies extracted from reference artifact".formatted(versions.size()));
            return versions;

        } catch (ArtifactDescriptorException e) {
            throw new EnforcerRuleException(
                    "Failed to resolve reference artifact " + groupId + ":" + artifactId + ":" + version, e);
        }
    }

    @Override
    public String toString() {
        return "DependencyAlignmentRule{" +
                "referenceArtifact='" + referenceArtifact + '\'' +
                ", dependencies=" + dependencies +
                '}';
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Verify the GAV exists: search the repository or run mvn dependency:get -Dartifact=g:a:v
Run mvn install for the reference artifact if it is a locally developed platform/BOM
Check repository configuration (settings.xml mirrors/credentials) and network access; retry after fixing
Clear a corrupted local cache entry: delete ~/.m2/repository/<group path>/<artifact>/<version> and rebuild

Example fix

// before: version not published anywhere
<referenceArtifact>org.hibernate.orm:hibernate-platform:9.9.9.Local</referenceArtifact>
// after: published version, or install locally first
<referenceArtifact>org.hibernate.orm:hibernate-platform:7.3.0.Final</referenceArtifact>

Defensive patterns

Strategy: try-catch

Validate before calling

// Shell: verify resolvability before enabling the rule
mvn dependency:get -Dartifact=org.hibernate.orm:hibernate-platform:7.3.0.Final -Dtransitive=false

Try / catch

try {
    rule.execute();
} catch (EnforcerRuleException e) {
    if (e.getMessage().startsWith("Failed to resolve reference artifact")) {
        getLog().warn("Reference artifact unreachable; check repositories/network/offline mode", e);
    } else throw e;
}

Prevention

Reference only published versions, or run mvn install for locally built platforms
Configure required repositories/mirrors in settings.xml, including credentials
Avoid -o (offline) mode for builds that resolve the reference artifact
Pin the platform version rather than a moving -SNAPSHOT

When it happens

Trigger: referenceDependencyVersions -> resolveReferenceArtifact called with coordinates that Maven cannot resolve: artifactId/version typo, artifact not published to any configured repository, or network/repository failure during descriptor read.

Common situations: Pointing referenceArtifact at a locally-built version that was never mvn install-ed; a repository is down or credentials missing; using a version that was deleted from Maven Central; offline builds.

Related errors

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