WARNING: %s not added to bootstrap class loader search:

Error message

WARNING: %s not added to bootstrap class loader search:

What it means

Warning prefix printed when AddToBootstrapClassLoaderSearch failed for a Boot-Class-Path entry: the named path was not added to the bootstrap class loader search, and the reason follows on the same line (illegal argument / not a JAR, or an unexpected JVMTI error). Startup continues; instrumentation classes from that path will not be found by the bootstrap loader.

Source

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

                    fprintf(stderr, "WARNING: unable to canonicalize %s\n", jarfile);
                    free(path);
                    continue;
                }
                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);
    }

View on GitHub (pinned to 88dfb74bbe)

Solutions

Read the suffix on the same stderr line to get the exact cause before acting
Verify each Boot-Class-Path entry is an existing JAR file readable by the JVM
Ship the missing boot jars with the agent or remove stale entries from the manifest
Confirm boot loading works via -Xlog:class+load=info | grep 'boot'

Example fix

# before
Boot-Class-Path: /opt/agent/does-not-exist.jar
# after
Boot-Class-Path: /opt/agent/agent-boot.jar   # actually shipped with the agent

Defensive patterns

Strategy: validation

Validate before calling

// verify every Boot-Class-Path entry is an existing jar
for (String e : bootEntries) {
    Path p = Path.of(e);
    if (!Files.isRegularFile(p) || !p.toString().endsWith(".jar"))
        throw new IllegalStateException("bad Boot-Class-Path entry: " + e);
}

Prevention

Ship and checksum all boot jars referenced by the agent manifest
Watch target JVM stderr at startup for 'not added to bootstrap class loader search' warnings in CI

When it happens

Trigger: Boot-Class-Path entry pointing to a directory or non-JAR file, a nonexistent file, or a path the JVMTI call rejects.

Common situations: Agents packaged expecting classes in an extra boot jar that was not shipped; documentation saying to copy a support jar that is missing; pointing Boot-Class-Path at a class directory instead of a jar.

Related errors

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