apache/kafka · error · MojoFailureException

No org.apache.kafka:* dependencies found on the project clas

Error message

No org.apache.kafka:* dependencies found on the project classpath. The checker cannot derive an API surface and would produce a meaningless '0 violations' report — likely a classpath or configuration issue.

What it means

Maven mojo equivalent of the Gradle task's no-kafka-dependency error. Thrown by KafkaInternalApiCheckerMojo.handleNoKafkaDependency() as a MojoFailureException when failOnNoKafkaDependency is true and getKafkaJarsFromDependencies() returned an empty list. The mojo scans project.getArtifacts() for entries whose groupId equals 'org.apache.kafka' (line 197) to build the API surface; with none present, the scan would be meaningless.

Source

Thrown at api-checker/maven-plugin/src/main/java/org/apache/kafka/maven/KafkaInternalApiCheckerMojo.java:132

            handleNoKafkaDependency();
            return;
        }

        List<File> classRoots = PublicApiChecker.collectExistingRoots(classesDirectories);
        if (classRoots.isEmpty()) {
            getLog().info("No class files found, skipping internal API check");
            return;
        }

        runCheck(kafkaJars, classRoots);
    }

    private void handleNoKafkaDependency() throws MojoFailureException {
        String msg = "No org.apache.kafka:* dependencies found on the project classpath. "
                + "The checker cannot derive an API surface and would produce a meaningless "
                + "'0 violations' report — likely a classpath or configuration issue.";
        if (failOnNoKafkaDependency) {
            throw new MojoFailureException(msg);
        }
        getLog().warn(msg + " Skipping internal API check. "
                + "Set <failOnNoKafkaDependency>true</failOnNoKafkaDependency> to make this fatal.");
    }

    private void runCheck(List<File> kafkaJars, List<File> classRoots)
            throws MojoExecutionException, MojoFailureException {
        try {
            getLog().info("Scanning " + classRoots.size() + " class file root(s) for internal API usage");
            CheckResult result = new PublicApiChecker(kafkaJars).checkBytecode(classRoots);
            reportResults(result);
        } catch (IOException e) {
            throw new MojoExecutionException("Failed to check internal API usage: " + e.getMessage(), e);
        }
    }

    private void reportResults(CheckResult result) throws MojoFailureException, IOException {
        List<PublicApiViolation> violations = result.violations();

View on GitHub (pinned to c31c9215e1)

Solutions

Add the Kafka dependency to the module: <dependency><groupId>org.apache.kafka</groupId><artifactId>kafka-clients</artifactId><version>3.8.0</version></dependency>.
If the Kafka dependency is shaded or relocated, manually configure the jars via the classesDirectories parameter or fork the plugin to extend the groupId filter.
If the module legitimately has no Kafka surface, disable the mojo for it: -Dkafka.internal-api-checker.enabled=false, or set <failOnNoKafkaDependency>false</failOnNoKafkaDependency> to fall back to warn-and-skip.
If the plugin was inherited from a parent pom but only applies to some modules, move it into a profile or attach <execution> only to the Kafka-consuming modules.

Example fix

<!-- before -->
<plugin>
  <groupId>org.apache.kafka</groupId>
  <artifactId>kafka-internal-api-checker-maven-plugin</artifactId>
  <configuration><failOnNoKafkaDependency>true</failOnNoKafkaDependency></configuration>
</plugin>
<!-- (no org.apache.kafka dependency in this module) -->

<!-- after -->
<dependencies>
  <dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>3.8.0</version>
  </dependency>
</dependencies>

Defensive patterns

Strategy: validation

Validate before calling

<!-- pom.xml: ensure an org.apache.kafka artifact is a compile/runtime dependency -->
<dependency>
  <groupId>org.apache.kafka</groupId>
  <artifactId>kafka-clients</artifactId>
  <version>${kafka.version}</version>
</dependency>
# pre-check before invoking the mojo:
# mvn -q dependency:list | grep org.apache.kafka || echo 'NO KAFKA DEPENDENCY'

Prevention

Declare at least one org.apache.kafka:* dependency in the module running the mojo; the checker scans project.getArtifacts() for that groupId.
Set <failOnNoKafkaDependency>true</failOnNoKafkaDependency> in CI builds so a missing dependency fails rather than silently reporting 0 violations.
After dependency changes, run mvn dependency:tree and confirm the kafka artifact appears under compile/runtime scope.

When it happens

Trigger: execute() line 113-116: kafkaJars.isEmpty() is true, handleNoKafkaDependency() runs, and failOnNoKafkaDependency is true. Produced when the Maven project has no org.apache.kafka:* dependency on its compile+runtime classpath (ResolutionScope.COMPILE_PLUS_RUNTIME) and the strict flag is enabled in pom.xml or via -Dkafka.internal-api-checker.failOnNoKafkaDependency=true.

Common situations: A Kafka-using module whose dependency was removed or scope-changed to test-only; pom using a shaded/relocated Kafka artifact whose groupId is no longer org.apache.kafka; a new module where the dependency was never declared; a profile that strips the Kafka dependency in some environments; running mvn verify on a module that does not actually depend on Kafka but inherited the plugin via parent pom.

Related errors

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/101ba133205f22f9.json. Report an issue: GitHub.