System class loader does not define the appendToClassPathFor

Error message

System class loader does not define the appendToClassPathForInstrumentation method\n

What it means

Diagnostic printed by appendClassPath: JVMTI AddToSystemClassLoaderSearch returned JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED, meaning the system class loader does not define (or did not accept) appendToClassPathForInstrumentation. appendClassPath returns -1, which callers turn into either a fatal premain abort (startup) or AGENT_ERROR_NOTONCP (attach).

Source

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

/*
 * Append the given jar file to the system class path. This should succeed in the
 * onload phase but may fail in the live phase if the system class loader doesn't
 * support appending to the class path.
 */
static int
appendClassPath( JPLISAgent* agent,
                 const char* jarfile ) {
    jvmtiEnv* jvmtienv = jvmti(agent);
    jvmtiError jvmtierr;

    jvmtierr = (*jvmtienv)->AddToSystemClassLoaderSearch(jvmtienv, jarfile);
    check_phase_ret_1(jvmtierr);

    switch (jvmtierr) {
        case JVMTI_ERROR_NONE :
            return 0;
        case JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED :
            fprintf(stderr, "System class loader does not define "
                "the appendToClassPathForInstrumentation method\n");
            break;
        default:
            fprintf(stderr, "Unexpected error (%d) returned by "
                "AddToSystemClassLoaderSearch\n", jvmtierr);
            break;
    }
    return -1;
}


/*
 * res = func, free'ing the previous value of 'res' if function
 * returns a new result.
 */
#define TRANSFORM(res,func) {    \
    char* tmp = func;            \
    if (tmp != res) {            \

View on GitHub (pinned to 88dfb74bbe)

Solutions

Use the default system class loader (remove -Djava.system.class.loader)
Make the custom loader extend URLClassLoader or implement the append behavior
Place agent classes on the initial classpath so no append is required
For frameworks with dedicated agent support, use their integration point instead of attach

Example fix

// before
class IsolatingLoader extends ClassLoader { ... } // used as java.system.class.loader
// after
class IsolatingLoader extends URLClassLoader { ... } // append-capable

Defensive patterns

Strategy: validation

Validate before calling

// guard: only attach when the system loader can append
ClassLoader sys = ClassLoader.getSystemClassLoader();
boolean appendable = false;
try { appendable = ClassLoader.class.getMethod("appendToClassPathForInstrumentation", String.class) != null; } catch (NoSuchMethodException ignored) {}
if (!appendable) throw new UnsupportedOperationException("system loader not appendable: " + sys.getClass().getName());

Prevention

Avoid -Djava.system.class.loader unless the loader explicitly supports instrumentation
Keep the default AppClassLoader for processes that host attach-based tooling

When it happens

Trigger: -javaagent at launch or VirtualMachine.loadAgent at runtime while the system class loader is a custom class that does not support appending to its search path.

Common situations: -Djava.system.class.loader with app-server/framework loaders; environments that deliberately lock the system classpath for security.

Related errors

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