apache/kafka · error · GradleException

Failed to check public API: {errorMessage}

Error message

Failed to check public API: {errorMessage}

What it means

Wrapped I/O failure raised by KafkaPublicApiCheckerTask.checkPublicApi() when PublicApiChecker construction or checkPublicApiConsistency(jarFile) throws an IOException. The original IOException is the cause; its message is appended so the exact failing file (project jar, reference jar, or javadoc jar entry) is visible. This is an infrastructure error reading inputs, not a consistency violation.

Source

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

                if (unjustified > 0) {
                    getLogger().warn("{} suppression(s) carry no reason — KIP-1265 requires a justification on every @SuppressKafkaInternalApiUsage", unjustified);
                }
            }
            if (!violations.isEmpty()) {
                String message = String.format("Found %d public API violations. See report: %s",
                    violations.size(), report.getAbsolutePath());

                if (failOnViolation.get()) {
                    throw new GradleException(message);
                } else {
                    getLogger().warn(message);
                }
            } else {
                getLogger().info("No public API violations found.");
            }

        } catch (IOException e) {
            throw new GradleException("Failed to check public API: " + e.getMessage(), e);
        }
    }

    private File getJavadocJarFile() {
        if (!javadocJarPath.isPresent()) {
            throw new GradleException("kafkaPublicApiChecker.javadocJarPath is not set. "
                    + "Either configure it explicitly on the extension, or apply this plugin to a "
                    + "project that defines a 'javadocJar' Jar task whose output the plugin can "
                    + "wire automatically.");
        }
        return javadocJarPath.get().getAsFile();
    }

    @Input
    public Property<Boolean> getCheckerEnabled() {
        return enabled;
    }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Re-run after a clean: ./gradlew clean javadocJar kafkaPublicApiCheck --rerun-tasks to rule out partial outputs.
2. Inspect the IOException cause for the specific path that failed, then verify the file (ls -l, unzip -t <jar>, jar tf <jar>).
3. If the file is corrupt, delete it and the Gradle cache entry for that artifact and re-resolve: ./gradlew --refresh-dependencies.
4. Free disk space / fix permissions / stop concurrent daemons (./gradlew --stop) if the cause points at a transient OS-level failure.
5. On network-mounted filesystems, move build dir and Gradle cache to local storage.

// Pre-check: report dir writable, javadoc jar and project jars readable
val out = layout.buildDirectory.dir("reports").get().asFile
check(out.exists() || out.mkdirs()) { "cannot create ${out.absolutePath}" }

try {
    tasks.named<org.apache.kafka.gradle.KafkaPublicApiCheckerTask>("kafkaPublicApiChecker").get().checkPublicApi()
} catch (e: org.gradle.api.GradleException) {
    if (e.message?.startsWith("Failed to check public API") == true && e.cause is java.io.IOException) {
        logger.warn("Public API check skipped (transient IO: ${e.cause?.message}); rerun.")
    } else {
        throw e
    }
}

When it happens

Trigger: Line 130-131 in the catch (IOException) block. Triggers: a project/reference jar is corrupt or concurrently deleted while being scanned; the javadoc jar is a zip that fails to open (truncated download, partial write); a configured path is inaccessible due to permissions; the Gradle build cache returned a corrupt cached artifact.

Common situations: Concurrent builds mutating build/libs or the Gradle cache; an interrupted jar task leaving a partial jar; CI on a constrained filesystem (NFS, overlay with inode limits); disk-full truncating outputs; antivirus locking zip entries during read.

Related errors

• Failed to check internal API usage: {errorMessage}
• Failed to check internal API usage: {errorMessage}
• No org.apache.kafka:* dependencies found on the configured k
• Found %d internal API usage violations. See report: %s
• Javadoc JAR file not found: {path}. Make sure the javadoc ta

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