quarkusio/quarkus · error · EnforcerRuleException

${illegalRuntimeGAVs.size()} illegal runtime dependencies fo

Error message

${illegalRuntimeGAVs.size()} illegal runtime dependencies found that have to be replaced with their -deployment counterparts:
	${joined}

What it means

The BansRuntimeDependency enforcer rule scans a Maven module's runtime dependencies and rejects any Quarkus runtime artifact (quarkus-<ext>) that has a corresponding -deployment artifact, because Quarkus convention requires build-time code to depend on the -deployment artifact instead. When at least one such illegal dependency is found it throws EnforcerRuleException listing all offending artifactIds.

Source

Thrown at independent-projects/enforcer-rules/src/main/java/io/quarkus/enforcer/BansRuntimeDependency.java:35

@Named("bansRuntimeDependency")
public class BansRuntimeDependency extends DeploymentDependencyRuleSupport {

    @Override
    protected void execute(MavenProject project, Map<String, Artifact> nonDeploymentArtifactsByGAV,
            Map<String, Dependency> directDepsByGAV)
            throws EnforcerRuleException {

        String runtimeArtifactId = project.getArtifactId().replace(DEPLOYMENT_ARTIFACT_ID_SUFFIX, "");
        List<String> illegalRuntimeGAVs = nonDeploymentArtifactsByGAV.entrySet().parallelStream()
                .filter(entry -> directDepsByGAV.containsKey(entry.getKey())) // only direct deps
                .filter(entry -> !entry.getValue().getArtifactId().equals(runtimeArtifactId)) // "own" runtime dep is alowed
                .filter(entry -> parseDeploymentGAV(entry.getKey(), entry.getValue()).isPresent())
                .map(entry -> entry.getValue().getArtifactId())
                .sorted()
                .collect(Collectors.toList());

        if (!illegalRuntimeGAVs.isEmpty()) {
            throw new EnforcerRuleException(illegalRuntimeGAVs.size()
                    + " illegal runtime dependencies found that have to be replaced with their "
                    + DEPLOYMENT_ARTIFACT_ID_SUFFIX + " counterparts:\n\t"
                    + illegalRuntimeGAVs.stream().collect(Collectors.joining("\n\t")));
        }
    }

    @Override
    protected boolean isCheckRequired(MavenProject project) {
        return project.getArtifactId().endsWith(DEPLOYMENT_ARTIFACT_ID_SUFFIX);
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Add the matching -deployment dependency (quarkus-<name>-deployment) and remove/replace the runtime quarkus-<name> dependency where the rule requires it
If the runtime dependency is legitimately needed alongside, check the rule's exclusion configuration for allowed GAVs
Run mvn -pl <module> enforcer:enforce locally to iterate quickly until the list is empty

Example fix

<!-- before -->
<dependency><groupId>io.quarkus</groupId><artifactId>quarkus-arc</artifactId></dependency>
<!-- after (in a deployment module) -->
<dependency><groupId>io.quarkus</groupId><artifactId>quarkus-arc-deployment</artifactId></dependency>

Defensive patterns

Strategy: validation

Validate before calling

// Shell: preview offending runtime GAVs before the build
mvn dependency:list -DincludeGroupIds=io.quarkus | grep -E 'quarkus-[a-z0-9-]+:jar' \
  | sed 's/.*quarkus-/quarkus-/' | sort

Try / catch

// EnforcerRuleException aborts the Maven build; handle at build level
try {
    mvn verify
} catch (BuildFailure e) {
    // parse the listed artifactIds, convert each runtime dep to -deployment
}

Prevention

In Quarkus deployment modules, always depend on *-deployment artifacts, never plain runtime ones
Use the Quarkus parent pom / archetypes which pre-wire the correct dependency pattern
Run mvn enforcer:enforce locally before pushing
When adding an extension dependency, copy from an existing extension pom of the same kind

When it happens

Trigger: Running mvn enforcer:enforce (via mvn verify on Quarkus modules) while a module's <dependencies> contains a quarkus-<name> runtime artifact that has a quarkus-<name>-deployment counterpart in the same reactor/dependency set and is not explicitly excluded from the check.

Common situations: Adding a new Quarkus extension dependency to a core/deployment module and forgetting the sibling -deployment dependency; copy-pasting runtime GAVs into deployment poms; renaming an extension so the rule now matches it.

Related errors

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