{"record":{"id":"dd9e86019a212ce0","repo":"openjdk/jdk","slug":"agent-error-notoncp","errorCode":"AGENT_ERROR_NOTONCP","errorMessage":"Unable to add %s to system class path - not supported by system class loader or configuration error!\\n","messagePattern":"Unable to add (.+?) to system class path - not supported by system class loader or configuration error!\\\\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/java.instrument/share/native/libinstrument/InvocationAdapter.c","lineNumber":362,"sourceCode":"            if (options != NULL) free(options);\n            return AGENT_ERROR_BADJAR;\n        }\n\n        agentClass = getAttribute(attributes, \"Agent-Class\");\n        if (agentClass == NULL) {\n            fprintf(stderr, \"Failed to find Agent-Class manifest attribute from %s\\n\",\n                jarfile);\n            free(jarfile);\n            if (options != NULL) free(options);\n            freeAttributes(attributes);\n            return AGENT_ERROR_BADJAR;\n        }\n\n        /*\n         * Add the jarfile to the system class path\n         */\n        if (appendClassPath(agent, jarfile)) {\n            fprintf(stderr, \"Unable to add %s to system class path \"\n                \"- not supported by system class loader or configuration error!\\n\",\n                jarfile);\n            free(jarfile);\n            if (options != NULL) free(options);\n            freeAttributes(attributes);\n            return AGENT_ERROR_NOTONCP;\n        }\n\n        /*\n         * The value of the Agent-Class attribute becomes the agent\n         * class name. The manifest is in UTF8 so need to convert to\n         * modified UTF8 (see JNI spec).\n         */\n        oldLen = (int)strlen(agentClass);\n        newLen = modifiedUtf8LengthOfUtf8(agentClass, oldLen);\n        /*\n         * According to JVMS class name is represented as CONSTANT_Utf8_info,\n         * so its length is u2 (i.e. must be <= 0xFFFF).","sourceCodeStart":344,"sourceCodeEnd":380,"githubUrl":"https://github.com/openjdk/jdk/blob/88dfb74bbeefcf2b0aa11835183bcd949998fc8f/src/java.instrument/share/native/libinstrument/InvocationAdapter.c#L344-L380","documentation":"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).","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"# before\njava -Djava.system.class.loader=com.myapp.IsolatingLoader -jar app.jar\n# after\njava -jar app.jar   # default loader supports appendToClassPathForInstrumentation","handlingStrategy":"validation","validationCode":"// refuse to attach when a custom system loader is configured\nString loader = ManagementFactory.getRuntimeMXBean()\n        .getInputArguments().stream()\n        .filter(a -> a.startsWith(\"-Djava.system.class.loader=\")).findFirst().orElse(\"\");\nif (!loader.isEmpty()) throw new IllegalStateException(\"attach unsupported with custom system loader: \" + loader);","typeGuard":null,"tryCatchPattern":"try { vm.loadAgent(agentPath); }\ncatch (AgentInitializationException e) {\n    if (e.returnValue() == 104) log.warn(\"NOTONCP: target uses non-appendable system class loader\");\n}","preventionTips":["Document that attach-based tooling requires the default system class loader","When a custom loader is mandatory, preload agent classes on the classpath instead"],"tags":["java-instrument","attach-api","classloader","classpath","agent-error-notoncp"],"backgroundTag":null,"analyzedSha":"88dfb74bbeefcf2b0aa11835183bcd949998fc8f","analyzedAt":"2026-08-14T11:45:09.665Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}