AGENT_ERROR_NOTONCP

AGENT_ERROR_NOTONCP

Error message

Unable to add %s to system class path - not supported by system class loader or configuration error!\n

What it means

Attach-path error (AGENT_ERROR_NOTONCP = 104): before invoking agentmain the JVM must add the agent jar to the system class loader search via JVMTI AddToSystemClassLoaderSearch; that step failed because the loader does not support appending or a configuration error occurred. Attach aborts with AgentInitializationException(104).

Source

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

            if (options != NULL) free(options);
            return AGENT_ERROR_BADJAR;
        }

        agentClass = getAttribute(attributes, "Agent-Class");
        if (agentClass == NULL) {
            fprintf(stderr, "Failed to find Agent-Class manifest attribute from %s\n",
                jarfile);
            free(jarfile);
            if (options != NULL) free(options);
            freeAttributes(attributes);
            return AGENT_ERROR_BADJAR;
        }

        /*
         * Add the jarfile to the system class path
         */
        if (appendClassPath(agent, jarfile)) {
            fprintf(stderr, "Unable to add %s to system class path "
                "- not supported by system class loader or configuration error!\n",
                jarfile);
            free(jarfile);
            if (options != NULL) free(options);
            freeAttributes(attributes);
            return AGENT_ERROR_NOTONCP;
        }

        /*
         * The value of the Agent-Class attribute becomes the agent
         * class name. The manifest is in UTF8 so need to convert to
         * modified UTF8 (see JNI spec).
         */
        oldLen = (int)strlen(agentClass);
        newLen = modifiedUtf8LengthOfUtf8(agentClass, oldLen);
        /*
         * According to JVMS class name is represented as CONSTANT_Utf8_info,
         * so its length is u2 (i.e. must be <= 0xFFFF).

View on GitHub (pinned to 88dfb74bbe)

Solutions

Remove or fix -Djava.system.class.loader so the default AppClassLoader (which supports appending) is used
If a custom loader is required, make it extend URLClassLoader or otherwise be appendable, or preload the agent classes on the classpath instead
Package the agent classes on the initial classpath so no append is needed
Prefer -javaagent at startup for JVMs with custom loaders

Example fix

# before
java -Djava.system.class.loader=com.myapp.IsolatingLoader -jar app.jar
# after
java -jar app.jar   # default loader supports appendToClassPathForInstrumentation

Defensive patterns

Strategy: validation

Validate before calling

// refuse to attach when a custom system loader is configured
String loader = ManagementFactory.getRuntimeMXBean()
        .getInputArguments().stream()
        .filter(a -> a.startsWith("-Djava.system.class.loader=")).findFirst().orElse("");
if (!loader.isEmpty()) throw new IllegalStateException("attach unsupported with custom system loader: " + loader);

Try / catch

try { vm.loadAgent(agentPath); }
catch (AgentInitializationException e) {
    if (e.returnValue() == 104) log.warn("NOTONCP: target uses non-appendable system class loader");
}

Prevention

Document that attach-based tooling requires the default system class loader
When a custom loader is mandatory, preload agent classes on the classpath instead

When it happens

Trigger: Attaching an agent to a JVM whose system class loader does not implement appendToClassPathForInstrumentation (custom -Djava.system.class.loader that is not a URLClassLoader subclass), or the append attempt failed (e.g. jar path invalid at that moment).

Common situations: Apps launched with -Djava.system.class.loader pointing to a custom launcher classloader (app servers, some frameworks); attaching to JVMs started with classloader-isolating launchers.

Related errors

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