What causes "Failed to check internal API usage: {}" in apache/kafka?

Re-read the cause in the stack trace — getMessage() of the wrapped IOException names the offending file/path.

apache/kafka · error · GradleException

Failed to check internal API usage: {}

Error message

Failed to check internal API usage: {}

What it means

Wrapped IOException thrown by KafkaInternalApiCheckerTask.runCheck when PublicApiChecker.checkBytecode fails to read class files or kafka jars. The original IOException is attached as the cause so the I/O failure reason is preserved. This indicates a filesystem/IO problem during the bytecode scan, not an API violation.

Source

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

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

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

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

        ViolationReporter reporter = new ViolationReporter();
        File report = reportFile.get().getAsFile();
        reporter.writeTextReport(violations, suppressions, report);
        reporter.printToConsole(violations, suppressions);

        getLogger().info("Internal API usage check completed. Report written to: {}", report.getAbsolutePath());

        long unjustified = suppressions.stream().filter(PublicApiViolation::lacksReason).count();
        if (unjustified > 0) {
            getLogger().warn("{} suppression(s) carry no reason — KIP-1265 requires a justification on every @SuppressKafkaInternalApiUsage", unjustified);
        }

View on GitHub (pinned to 996fb4585a)

Solutions

Re-read the cause in the stack trace — getMessage() of the wrapped IOException names the offending file/path.
Run ./gradlew clean and rebuild so class roots and jars are regenerated consistently.
If a dependency jar is corrupt, clear the Gradle cache entry (~/.gradle/caches/modules-2/...) and re-resolve.
On Windows/CI, ensure no other process holds an exclusive lock on build outputs, and disable parallel daemons if files are being deleted mid-build.

Defensive patterns

Strategy: retry

Validate before calling

// Pre-flight: ensure all configured roots/jars are readable
List<File> inputs = new ArrayList<>(kafkaDependencyJars.getFiles());
inputs.addAll(PublicApiChecker.collectExistingRoots(classDirs.get().getFiles()));
for (File f : inputs) {
  if (!f.exists() || !f.canRead()) throw new IllegalStateException("Unreadable input: " + f);
}

Try / catch

try { checkInternalApiUsage() } catch (GradleException e) { if (e.cause instanceof IOException) { logger.error('I/O during scan: ' + e.cause.message); /* clean + retry once */ } else throw e }

Prevention

Run ./gradlew clean before the check on CI to avoid mid-run file deletion.
Avoid parallel daemons deleting shared build outputs.
Periodically purge corrupt jars from the Gradle cache.

When it happens

Trigger: new PublicApiChecker(kafkaJars).checkBytecode(classRoots) (line 116) throws IOException. Triggers when a configured class root or kafka jar is unreadable, deleted between configuration and execution, is a corrupt zip/jar, or the build runs with insufficient file permissions.

Common situations: Concurrent Gradle daemons or another process deleting build/ outputs mid-scan; stale/locked jar on Windows; corrupt downloaded dependency jar in the Gradle cache; classDirs pointing at a path that no longer exists after clean.

Related errors

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