elastic/elasticsearch · error · GradleException

Failed to load one of the given class files.

Error message

Failed to load one of the given class files.

What it means

Thrown when checker.addClassesToCheck raises an IOException while loading the class files to be checked. The forbidden-apis checker could not read or parse the supplied class files (getClassFiles()), so it cannot scan them for forbidden API usage.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/precommit/CheckForbiddenApisTask.java:536

                } catch (ParseException pe) {
                    throw new InvalidUserDataException("Parsing signatures failed: " + pe.getMessage(), pe);
                }

                if (checker.hasNoSignatures()) {
                    if (checker.noSignaturesFilesParsed()) {
                        throw new InvalidUserDataException(
                            "No signatures were added to task; use properties 'signatures', 'bundledSignatures', 'signaturesURLs', and/or 'signaturesFiles' to define those!"
                        );
                    } else {
                        logger.info("Skipping execution because no API signatures are available.");
                        return;
                    }
                }

                try {
                    checker.addClassesToCheck(getParameters().getClassFiles());
                } catch (IOException ioe) {
                    throw new GradleException("Failed to load one of the given class files.", ioe);
                }
                checker.run();
                writeMarker(getParameters().getSuccessMarker().getAsFile().get());
            } catch (ForbiddenApiException e) {
                throw new VerificationException("Forbidden API verification failed", e);
            } catch (Exception e) {
                throw new RuntimeException(e);
            } finally {
                // Close the classloader to free resources:
                try {
                    if (urlLoader != null) urlLoader.close();
                } catch (IOException ioe) {
                    // getLogger().warn("Cannot close classloader: ".concat(ioe.toString()));
                }
            }
        }

        private void writeMarker(File successMarker) throws IOException {

View on GitHub (pinned to db6a809a66)

Solutions

1. Clean and recompile: ./gradlew clean compileJava (or the relevant compile task) before the forbidden-apis task.
2. Inspect the wrapped IOException for the failing class path.
3. Confirm the task's classFiles input is wired to the correct source set output directory.
4. Check permissions / disk space on the build directory.

// Confirm the class files input is non-empty and all files exist
List<File> classes = getClassFiles();
if (classes.isEmpty()) throw new InvalidUserDataException("No class files to check; did compilation run?");
for (File c : classes) if (!c.isFile()) throw new InvalidUserDataException("Missing class file: " + c);

try {
    checker.addClassesToCheck(getClassFiles());
} catch (GradleException e) {
    if (e.getCause() instanceof IOException) {
        // clean & recompile, then re-run this task
        throw new GradleException("Class files unreadable; run clean compileJava first", e);
    }
    throw e;
}

When it happens

Trigger: A class file in getClassFiles() that is missing, unreadable, truncated, or not valid bytecode at the moment the checker loads it.

Common situations: Running the forbidden-apis task before compilation finished; stale build outputs referencing deleted classes; corrupted class files from an interrupted compile; file permission issues on the build output dir.

Related errors

• IO problem while reading files with API signatures.
• Cannot read ${f} to check for duplicate license headers
• Cannot generate license header report for ${path}
• Parsing signatures failed: {}
• No signatures were added to task; use properties 'signatures

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/43cf4ce49096036d. Report an issue: GitHub.