elastic/elasticsearch · error · VerificationException

Forbidden API verification failed

Error message

Forbidden API verification failed

What it means

The actual forbidden-API violation result: checker.run() raised a ForbiddenApiException, which the task wraps in a Gradle VerificationException. This is the task doing its job — it found a reference to an API that the configured signatures forbid (e.g. System.out, internal JDK APIs, deprecated APIs). It is a code-quality failure, not an infrastructure fault.

Source

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

                    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 {
            Files.write(successMarker.toPath(), new byte[] {}, StandardOpenOption.CREATE);
        }

        private URLClassLoader createClassLoader(FileCollection classpath, FileCollection classesDirs) {
            if (classesDirs == null || classpath == null) {

View on GitHub (pinned to db6a809a66)

Solutions

1. Read the VerificationException's cause and the preceding checker output lines — they name each violating class, method, and which signature matched.
2. Fix the offending code to use the permitted alternative (SLF4J/LogManager logger instead of System.out, public API instead of sun.*, etc.).
3. If the call is genuinely required, scope a suppress annotation or a narrowly-targeted signatures relaxation per the project's policy.
4. Do NOT widen the suppression broadly; re-run the task to confirm zero violations.

Example fix

// before
System.out.println("debug: " + value);

// after
private static final Logger logger = LogManager.getLogger(Foo.class);
logger.debug("debug: {}", value);

try {
    checker.run();
} catch (ForbiddenApiException e) {
    // expected path when violations exist: the task wraps it in VerificationException.
    // Each violation is already logged above; fix the cited call sites, do not catch-and-ignore in real builds.
    throw e;
}

When it happens

Trigger: Any class in getClassFiles() references a method/field/package listed in the configured signatures or bundled signatures; the checker reports each violation then throws.

Common situations: New code that uses System.out/err, an internal sun.* API, a deprecated method, or an unsafe deserialization API; pulling in a dependency that itself was compiled against now-forbidden APIs; tightening bundledSignatures.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• IO problem while reading files with API signatures.
• Parsing signatures failed: {}
• No signatures were added to task; use properties 'signatures
• Failed to load one of the given class files.
• Missing 'classesDirs' or 'classpath' property.

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