apache/kafka · error · GradleException

Failed to check public API: {}

Error message

Failed to check public API: {}

What it means

GradleException wrapping an IOException, thrown from KafkaPublicApiCheckerTask.checkPublicApi's catch block. It signals that reading the javadoc jar, project jars, reference jars, or writing the report failed at the I/O level. The original IOException is the cause.

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 996fb4585a)

Solutions

1. Inspect the wrapped IOException cause for the exact path and reason.
2. Ensure build/reports/ is writable and the build dir is not read-only.
3. Re-run ./gradlew clean to regenerate jars and the reports directory consistently.
4. If a reference jar is corrupt, purge it from the Gradle cache and re-resolve.

// Pre-flight: writable report dir and readable jars
def reportDir = reportFile.get().asFile.parentFile
assert reportDir.directory || reportDir.mkdirs(): "cannot create report dir ${reportDir}"
[kafkaJars, projectJarFiles, referenceJarFiles].flatten().each { assert it.canRead(): "unreadable ${it}" }

try { checkPublicApi() } catch (GradleException e) { if (e.cause instanceof IOException) { logger.error('I/O: ' + e.cause.message); /* free disk, fix perms, clean */ } else throw e }

When it happens

Trigger: Any IOException thrown inside the try block at line ~89-130: PublicApiChecker construction/consistency check, or ViolationReporter.writeTextReport. Triggers on unreadable/locked/missing jar or an unwritable report directory.

Common situations: Report directory build/reports does not exist or is read-only; javadoc/project jar deleted mid-run; CI runner out of disk; corrupt reference jar in cache.

Related errors

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

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