What causes "Illegal argument or not JAR file\n" in openjdk/jdk?

Replace directory entries with a jar: jar cf extra.jar -C classes .

JVMTI_ERROR_ILLEGAL_ARGUMENT

JVMTI_ERROR_ILLEGAL_ARGUMENT

Error message

Illegal argument or not JAR file\n

What it means

The reason suffix for the bootstrap-add warning: JVMTI AddToBootstrapClassLoaderSearch returned JVMTI_ERROR_ILLEGAL_ARGUMENT, which per the JVMTI spec means the path is not a JAR file (directories and class files are rejected; only jars are legal for the bootstrap search) or the argument was otherwise invalid.

Source

Thrown at src/java.instrument/share/native/libinstrument/InvocationAdapter.c:967

                }
                parent = basePath(canonicalPath);
                jplis_assert(parent != (char*)NULL);
                haveBasePath = 1;
            }

            resolved = resolve(parent, path);
            jvmtierr = (*jvmtienv)->AddToBootstrapClassLoaderSearch(jvmtienv, resolved);
            free(resolved);
        }

        /* print warning if boot class path not updated */
        if (jvmtierr != JVMTI_ERROR_NONE) {
            check_phase_blob_ret(jvmtierr, free(path));

            fprintf(stderr, "WARNING: %s not added to bootstrap class loader search: ", path);
            switch (jvmtierr) {
                case JVMTI_ERROR_ILLEGAL_ARGUMENT :
                    fprintf(stderr, "Illegal argument or not JAR file\n");
                    break;
                default:
                    fprintf(stderr, "Unexpected error: %d\n", jvmtierr);
            }
        }

        /* finished with the path */
        free(path);
    }


    /* clean-up */
    if (haveBasePath && parent != canonicalPath) {
        free(parent);
    }
    free(paths);
}

View on GitHub (pinned to 88dfb74bbe)

Solutions

Replace directory entries with a jar: jar cf extra.jar -C classes .
Point Boot-Class-Path only at .jar files
For directories, use -Xbootclasspath/a:dir at JVM launch instead of the manifest attribute

Example fix

# before
Boot-Class-Path: classes/   # directory -> ILLEGAL_ARGUMENT
# after
Boot-Class-Path: extra-boot.jar

Defensive patterns

Strategy: validation

Validate before calling

// jars only for bootstrap search
if (!entry.endsWith(".jar") || !Files.isRegularFile(Path.of(entry)))
    throw new IllegalArgumentException("bootstrap entries must be existing JAR files: " + entry);

Prevention

Remember AddToBootstrapClassLoaderSearch accepts jars only — package directories into a jar
Use -Xbootclasspath/a at launch when directories must appear on the boot path

When it happens

Trigger: A Boot-Class-Path entry naming a directory, a .class file, a zip that is not a jar, or a path with a query/fragment component left untrimmed.

Common situations: Porting agents from the old -Xbootclasspath/a style (which accepted directories) to Boot-Class-Path manifests (jars only); build pipelines copying a classes/ directory where a jar is expected.

Related errors

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