apache/kafka · error · GradleException

Found public API violations. See report

Error message

Found %d public API violations. See report: %s

What it means

GradleException (or warning) from KafkaPublicApiCheckerTask.checkPublicApi when the public-API consistency check detects violations and failOnViolation is true. The message reports the violation count and the report path. This is the checker signalling that the published API differs from the reference/javadoc surface.

Solutions

1. Read the report at the path in the message — each PublicApiViolation names the missing/changed symbol.
2. Restore the removed/changed public API, or update the reference jars if the change is intended and reviewed.
3. Regenerate javadoc from the same source the jar was built from (dependsOn javadocJar + jar).
4. For intended breakage, annotate with @SuppressKafkaInternalApiUsage(reason=...) per KIP-1265; otherwise set failOnViolation=false only temporarily.

// Triage run with failOnViolation=false, then read the report
kafkaPublicApiChecker.failOnViolation = false

try { tasks.kafkaPublicApiChecker() } catch (GradleException e) { if (e.message.contains('public API violations')) { /* inspect report, restore API or update reference jars */ } else throw e }

When it happens

Trigger: violations list non-empty after checker.checkPublicApiConsistency(jarFile) at line 100-ish and failOnViolation.get() true. Triggered when symbols present in the javadoc jar are missing/changed in the project jars, or vice versa, relative to the configured reference jars.

Common situations: Adding/removing a public method without updating docs; binary-incompatible change between releases; reference jar out of date; javadoc generated from a different source state than the compiled jar.

Related errors

• Found internal API usage violations. See report
• Failed to check internal API usage
• Failed to check public API
• Found internal API usage violations. See report
• Javadoc JAR file not found

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

Appendix: source

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

            // Print summary to console
            reporter.printToConsole(violations, suppressions);

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

            if (!suppressions.isEmpty()) {
                getLogger().lifecycle("{} suppression(s) honoured — see report for justifications.", suppressions.size());
                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);
                }
            }
            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.");

View on GitHub (pinned to 996fb4585a)