{"record":{"id":"a62b8b7a350e9f09","repo":"apache/kafka","slug":"failed-to-check-internal-api-usage-a62b8b","errorCode":null,"errorMessage":"Failed to check internal API usage: {}","messagePattern":"Failed to check internal API usage: (.+?)","errorType":"exception","errorClass":"MojoExecutionException","httpStatus":null,"severity":"error","filePath":"api-checker/maven-plugin/src/main/java/org/apache/kafka/maven/KafkaInternalApiCheckerMojo.java","lineNumber":145,"sourceCode":"    private void handleNoKafkaDependency() throws MojoFailureException {\n        String msg = \"No org.apache.kafka:* dependencies found on the project classpath. \"\n                + \"The checker cannot derive an API surface and would produce a meaningless \"\n                + \"'0 violations' report — likely a classpath or configuration issue.\";\n        if (failOnNoKafkaDependency) {\n            throw new MojoFailureException(msg);\n        }\n        getLog().warn(msg + \" Skipping internal API check. \"\n                + \"Set <failOnNoKafkaDependency>true</failOnNoKafkaDependency> to make this fatal.\");\n    }\n\n    private void runCheck(List<File> kafkaJars, List<File> classRoots)\n            throws MojoExecutionException, MojoFailureException {\n        try {\n            getLog().info(\"Scanning \" + classRoots.size() + \" class file root(s) for internal API usage\");\n            CheckResult result = new PublicApiChecker(kafkaJars).checkBytecode(classRoots);\n            reportResults(result);\n        } catch (IOException e) {\n            throw new MojoExecutionException(\"Failed to check internal API usage: \" + e.getMessage(), e);\n        }\n    }\n\n    private void reportResults(CheckResult result) throws MojoFailureException, IOException {\n        List<PublicApiViolation> violations = result.violations();\n        List<PublicApiViolation> suppressions = result.suppressions();\n\n        ViolationReporter reporter = new ViolationReporter();\n        reporter.writeTextReport(violations, suppressions, reportFile);\n        reporter.printToConsole(violations, suppressions);\n\n        getLog().info(\"Internal API usage check completed. Report written to: \" + reportFile.getAbsolutePath());\n\n        long unjustified = suppressions.stream().filter(PublicApiViolation::lacksReason).count();\n        if (unjustified > 0) {\n            getLog().warn(unjustified + \" suppression(s) carry no reason — KIP-1265 requires a justification on every @SuppressKafkaInternalApiUsage\");\n        }\n","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/apache/kafka/blob/996fb4585aa1bcc8980b0e1b8d6b168b986cd979/api-checker/maven-plugin/src/main/java/org/apache/kafka/maven/KafkaInternalApiCheckerMojo.java#L127-L163","documentation":"MojoExecutionException wrapping an IOException, thrown by KafkaInternalApiCheckerMojo.runCheck when PublicApiChecker.checkBytecode fails to read the class roots or kafka jars. The Maven analogue of Gradle error 1 — an I/O problem during the bytecode scan, with the original IOException preserved as cause.","triggerScenarios":"new PublicApiChecker(kafkaJars).checkBytecode(classRoots) throws IOException inside the try at line 140. Triggers on unreadable/missing/deleted class roots or corrupt kafka jars.","commonSituations":"target/classes deleted between resolution and execution; corrupt kafka-clients jar in the local Maven repo (.m2); another process locking class files; classesDirectories pointing at a non-existent path.","solutions":["Read the wrapped IOException cause to find the failing path.","Run mvn clean compile to regenerate target/classes consistently.","If a kafka jar is corrupt, delete it from ~/.m2/repository/org/apache/kafka/ and re-resolve.","Validate that <classesDirectories> values exist on disk before the goal runs."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-flight in the mojo or a profile\nfor (File f : classRoots) if (!f.canRead()) throw new IllegalStateException(\"unreadable: \" + f);","typeGuard":null,"tryCatchPattern":"try { runCheck(...); } catch (MojoExecutionException e) { if (e.cause instanceof java.io.IOException) { getLog().error(e.cause.message); /* mvn clean, purge corrupt jar */ } else throw e; }","preventionTips":["Run mvn clean compile before the goal.","Purge corrupt kafka jars from ~/.m2.","Ensure classesDirectories exist on disk."],"tags":["maven","api-checker","io","filesystem"],"backgroundTag":null,"analyzedSha":"996fb4585aa1bcc8980b0e1b8d6b168b986cd979","analyzedAt":"2026-08-11T22:03:28.655Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}