apache/kafka · error · GradleException

Javadoc JAR file not found: {path}. Make sure the javadoc ta

Error message

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

What it means

Thrown by KafkaPublicApiCheckerTask.checkPublicApi() when javadocJarPath resolves to a File whose exists() check returns false. The task compares @InterfaceAudience.Public annotations across project jars against the generated javadoc HTML, so it requires the javadoc jar to already exist on disk at task execution time. The message tells the user the configured path and points at the missing prerequisite task.

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

Solutions

Run the javadocJar task first so the file exists: ./gradlew javadocJar kafkaPublicApiCheck.
If invoking the check task directly, make it depend on the producing task in the build script: tasks.named('kafkaPublicApiCheck').dependsOn('javadocJar').
Verify the configured path matches the actual output (e.g. build/libs/<project>-<version>-javadoc.jar); if javadocJarPath was hardcoded, point it at javadocJar.archiveFile instead.
If javadoc generation itself is failing or skipped, fix the upstream javadoc task (run ./gradlew javadoc --info) before re-running the checker.

Example fix

// before
kafkaPublicApiChecker {
  javadocJarPath = layout.buildDirectory.file('libs/myapp-javadoc.jar') // wrong name
}

// after — wire to the producing task's output so it always exists and is up-to-date
kafkaPublicApiChecker {
  javadocJarPath = tasks.named('javadocJar', Jar).flatMap { it.archiveFile }
}
tasks.named('kafkaPublicApiCheck').configure { dependsOn('javadocJar') }

Defensive patterns

Strategy: validation

Validate before calling

// Make the checker depend on javadocJar and verify the artifact exists before running
tasks.named("kafkaPublicApiChecker") { dependsOn("javadocJar") }
val jd = layout.buildDirectory.file("libs/${project.name}-${project.version}-javadoc.jar").get().asFile
check(jd.exists()) { "javadoc jar missing at ${jd.absolutePath}; run :javadocJar first" }

Type guard

fun File?.existingJar(): File? = this?.takeIf { it.exists() && it.isFile && it.extension == "jar" }

Prevention

Add dependsOn("javadocJar") (or wire the task dependency in the plugin block) so Gradle always produces the jar before the checker runs.
Run ./gradlew javadocJar once after a clean to confirm the javadoc generation itself succeeds — a broken javadoc task yields no jar.
Do not delete the javadoc jar between the docsJar and checker tasks in a custom clean hook.

When it happens

Trigger: Line 80-83: getJavadocJarFile() returns a path, but jarFile.exists() is false. Triggered when the plugin is configured with a javadocJarPath that points at a file the javadoc (or javadocJar) task never produced — e.g. the check task runs before javadocJar in the task graph, or the path was hand-set to a wrong location, or a clean wiped build/libs without re-running javadocJar.

Common situations: Running ./gradlew kafkaPublicApiCheck directly without depending on javadocJar; mis-configuring kafkaPublicApiChecker.javadocJarPath to a hardcoded path that diverges from the actual javadocJar output (e.g. wrong version suffix); CI that runs only the check task; a build scan after ./gradlew clean that skips the docs tasks.

Related errors

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