What causes "genstubs failed" in openjdk/jdk?

Look at the stack trace GenStubs prints to stdout right before returning false — it names the class and the parse/translate failure.

openjdk/jdk · error · BuildException

genstubs failed

Error message

genstubs failed

What it means

Thrown by the GenStubs Ant task when GenStubs.run() returns false in in-process mode. GenStubs parses JDK source files with the javac API and emits minimal 'stub' source files (signatures with throw new RuntimeException()) used to compile langtools against future-JDK APIs; failure means the internal compilation/translation step failed.

Source

Thrown at make/langtools/tools/anttasks/GenStubsTask.java:116

//            System.err.println("Ant.execute: srcDir " + srcDir);
//            System.err.println("Ant.execute: destDir " + destDir);
//            System.err.println("Ant.execute: files " + Arrays.asList(files));

        files = filter(srcDir, destDir, files);
        if (files.length == 0)
            return;
        System.out.println("Generating " + files.length + " stub files to " + destDir);

        List<String> classNames = new ArrayList<>();
        for (String file: files) {
            classNames.add(file.replaceAll(".java$", "").replace('/', '.'));
        }

        if (!fork) {
            GenStubs m = new GenStubs();
            boolean ok = m.run(srcDir.getPath(), destDir, classNames);
            if (!ok)
                throw new BuildException("genstubs failed");
        } else {
            List<String> cmd = new ArrayList<>();
            String java_home = System.getProperty("java.home");
            cmd.add(new File(new File(java_home, "bin"), "java").getPath());
            if (classpath != null)
                cmd.add("-Xbootclasspath/p:" + classpath);
            cmd.add(GenStubs.class.getName());
            cmd.add("-sourcepath");
            cmd.add(srcDir.getPath());
            cmd.add("-s");
            cmd.add(destDir.getPath());
            cmd.addAll(classNames);
            //System.err.println("GenStubs exec " + cmd);
            ProcessBuilder pb = new ProcessBuilder(cmd);
            pb.redirectErrorStream(true);
            try {
                Process p = pb.start();
                try (BufferedReader in = new BufferedReader(new InputStreamReader(p.getInputStream()))) {

View on GitHub (pinned to 88dfb74bbe)

Solutions

Look at the stack trace GenStubs prints to stdout right before returning false — it names the class and the parse/translate failure.
Confirm the task's srcDir and destDir attributes and that every filtered .java file exists under srcDir.
Update or remove the offending classes from the genstubs include list so they are no longer stubbed.
As a diagnostic, set fork='true' on the task to run GenStubs in a fresh JVM with -Xbootclasspath/p:classpath, isolating it from Ant's classpath.

Example fix

<!-- before -->
<genstubs srcdir="${langtools.src}" destdir="${build.gensrc}" include="**/*.java"/>

<!-- after: restrict to the APIs that actually need stubs -->
<genstubs srcdir="${langtools.src}" destdir="${build.gensrc}"
          include="java/lang/**/*.java,java/util/**/*.java"/>

Defensive patterns

Strategy: try-catch

Validate before calling

// verify every class to be stubbed resolves on the sourcepath before running
for (String cn : classNames) {
    Path f = Paths.get(srcDir, cn.replace('.', '/') + ".java");
    if (!Files.isReadable(f)) throw new IllegalStateException("missing source: " + f);
}

Try / catch

try {
    new GenStubs().run(sourcepath, outdir, classNames);
} catch (Throwable t) {
    // GenStubs.run() itself catches Throwable and returns false;
    // treat any stack trace printed by it as the authoritative diagnosis
    logger.error("genstubs failed for " + classNames, t);
    throw t;
}

Prevention

Pin the genstubs include list to stable, API-only packages instead of whole source trees.
Run genstubs in a clean build dir each time so partial stub output cannot accumulate.
Regenerate stubs whenever the underlying JDK source is updated, not on a stale checkout.

When it happens

Trigger: Invoking the genstubs target with fork=false (default) while any class listed in the file filter has a syntax error, references types missing from the sourcepath, or when the javac TreeScanner translation aborts (run() catches Throwable, prints a stack trace, and returns false).

Common situations: Building langtools against an in-progress JDK source tree where an API being stubbed changed shape; wrong srcDir attribute pointing at incomplete source; JDK version mismatch between the bootjavac and the source being parsed.

Related errors

AI-assisted analysis of openjdk/jdk@88dfb74bbe (2026-08-14). Data as JSON: /api/errors/f4e28e22ca9a8483. Report an issue: GitHub.