apache/kafka · error · GradleException

Javadoc JAR file not found: {}. Make sure the javadoc task h

Error message

Javadoc JAR file not found: {}. Make sure the javadoc task has run first.

What it means

GradleException from KafkaPublicApiCheckerTask.checkPublicApi when the resolved javadoc jar path does not exist on disk. The public-API checker parses the javadoc jar to derive the API surface, so it must be present. The message tells the user to run the javadoc task first — the checker does not depend on it automatically unless wired.

Source

Thrown at api-checker/gradle-plugins/src/main/java/org/apache/kafka/gradle/KafkaPublicApiCheckerTask.java:81

        setGroup("verification");
        setDescription("Checks consistency between javadoc HTML files and @InterfaceAudience.Public annotations across project JARs");

        // Set default values
        enabled.convention(true);
        failOnViolation.convention(true);
        reportFile.convention(getProject().getLayout().getBuildDirectory().file("reports/kafka-public-api-checker.txt"));
    }

    @TaskAction
    public void checkPublicApi() {
        if (!getCheckerEnabled().get()) {
            getLogger().info("KafkaPublicApiChecker is disabled, skipping...");
            return;
        }

        File jarFile = getJavadocJarFile();
        if (!jarFile.exists()) {
            throw new GradleException("Javadoc JAR file not found: " + jarFile.getAbsolutePath() +
                ". Make sure the javadoc task has run first.");
        }

        getLogger().info("Checking public API consistency in: {}", jarFile.getAbsolutePath());

        try {
            if (projectJarFiles.getFiles().isEmpty()) {
                throw new GradleException(
                        "No project JARs configured on kafkaPublicApiChecker.projectJarFiles — "
                        + "the checker needs at least one classes/jar source to build the API surface.");
            }
            PublicApiChecker checker = new PublicApiChecker(
                new ArrayList<>(projectJarFiles.getFiles()),
                new ArrayList<>(referenceJarFiles.getFiles()));
            CheckResult result = checker.checkPublicApiConsistency(jarFile);
            List<PublicApiViolation> violations = result.violations();
            List<PublicApiViolation> suppressions = result.suppressions();

View on GitHub (pinned to 996fb4585a)

Solutions

Wire the dependency: tasks.named('kafkaPublicApiChecker') { dependsOn 'javadocJar' } so the jar is built first.
Run ./gradlew javadocJar then ./gradlew kafkaPublicApiChecker.
Confirm javadocJarPath resolves to the actual jar (default build/libs/<project>-<version>-javadoc.jar) — log it or print getJavadocJarFile().getAbsolutePath().
If javadoc generation itself is disabled, enable it for the checked module or set javadocJarPath to a checked-in reference jar.

Example fix

// before
tasks.named('kafkaPublicApiChecker') { /* no dependsOn */ }
// after
tasks.named('kafkaPublicApiChecker') {
  dependsOn 'javadocJar'
  javadocJarPath = tasks.named('javadocJar').flatMap { it.archiveFile }
}

Defensive patterns

Strategy: validation

Validate before calling

// In build.gradle
tasks.named('kafkaPublicApiChecker') {
  dependsOn 'javadocJar'
  doFirst {
    def f = javadocJarPath.get().asFile
    assert f.exists(): "javadoc jar missing at ${f}; dependsOn(javadocJar) should have built it"
  }
}

Prevention

Always dependsOn 'javadocJar' from the checker task.
Point javadocJarPath at the producing task's archiveFile so Gradle tracks the dependency.
Do not run with -x javadocJar in CI.

When it happens

Trigger: getJavadocJarFile().exists() returns false at line 80. Happens when the task runs before the javadocJar task (no task dependency wired), or when javadocJarPath points to a stale/wrong path, or in a clean checkout where javadoc has never been generated.

Common situations: Invoking kafkaPublicApiChecker directly without dependsOn(javadocJar); misconfiguring javadocJarPath to a path that is never produced; running on a fresh clone; disabling the javadoc task via -x javadocJar.

Related errors

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/9a7a8edf46ea03fe. Report an issue: GitHub.