{"record":{"id":"86febbd8fd366fd3","repo":"openjdk/jdk","slug":"java-lang-instrument-javaagent-unknown-error-n","errorCode":null,"errorMessage":"java.lang.instrument/-javaagent: unknown error\\n","messagePattern":"java\\.lang\\.instrument/-javaagent: unknown error\\\\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/java.instrument/share/native/libinstrument/InvocationAdapter.c","lineNumber":285,"sourceCode":"    case JPLIS_INIT_ERROR_CANNOT_CREATE_NATIVE_AGENT:\n      result = JNI_ERR;\n      fprintf(stderr, \"java.lang.instrument/-javaagent: cannot create native agent.\\n\");\n      break;\n    case JPLIS_INIT_ERROR_FAILURE:\n      result = JNI_ERR;\n      fprintf(stderr, \"java.lang.instrument/-javaagent: initialization of native agent failed.\\n\");\n      break;\n    case JPLIS_INIT_ERROR_ALLOCATION_FAILURE:\n      result = JNI_ERR;\n      fprintf(stderr, \"java.lang.instrument/-javaagent: allocation failure.\\n\");\n      break;\n    case JPLIS_INIT_ERROR_AGENT_CLASS_NOT_SPECIFIED:\n      result = JNI_ERR;\n      fprintf(stderr, \"-javaagent: agent class not specified.\\n\");\n      break;\n    default:\n      result = JNI_ERR;\n      fprintf(stderr, \"java.lang.instrument/-javaagent: unknown error\\n\");\n      break;\n    }\n    return result;\n}\n\n/*\n * Agent_OnAttach returns a jint. 0/JNI_OK indicates success and non-0\n * indicates an error. To allow the attach mechanism throw an\n * AgentInitializationException with a reasonable exception message we define\n * a few specific errors here.\n */\n#define AGENT_ERROR_BADJAR    ((jint)100)  /* Agent JAR not found or no Agent-Class attribute */\n#define AGENT_ERROR_NOTONCP   ((jint)101)  /* Unable to add JAR file to system class path */\n#define AGENT_ERROR_STARTFAIL ((jint)102)  /* No agentmain method or agentmain failed */\n\n/*\n *  This will be called once each time a tool attaches to the VM and loads\n *  the JPLIS library.","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/openjdk/jdk/blob/88dfb74bbeefcf2b0aa11835183bcd949998fc8f/src/java.instrument/share/native/libinstrument/InvocationAdapter.c#L267-L303","documentation":"Fallback branch of the native agent initialization error mapper: JPLIS returned an initialization error code that has no dedicated case in the switch (i.e. not cannot-create, generic failure, allocation failure, or class-not-specified). It means an unrecognized/unanticipated failure occurred inside JPLISAgent initialization and the agent cannot start.","triggerScenarios":"A future/newer JPLIS init error code being rendered by an older libinstrument binary; JVM/JNI environment setup returning an unexpected status during Agent_OnLoad; corrupted or ABI-mismatched libinstrument vs. JVM (mixed JDK installations).","commonSituations":"Mixing native libraries from different JDK versions on the path (e.g. JAVA_HOME pointing at one JDK while another JDK's tools are invoked); running a custom-built instrument native lib against a different JVM build.","solutions":["Verify JAVA_HOME and PATH point to a single consistent JDK installation (no mixed JDK copies)","Re-run with -Xlog:library=info to see which native libraries load and from where","If using a custom-built JDK or agent, rebuild the instrument module against the exact JVM it runs on","Check the JVM release notes for new init error codes if the error appears after a JDK upgrade"],"exampleFix":"# before: mixed JDKs\nexport JAVA_HOME=/opt/jdk21 PATH=/opt/jdk17/bin:$PATH\n# after\nexport JAVA_HOME=/opt/jdk21 PATH=$JAVA_HOME/bin:$PATH","handlingStrategy":"validation","validationCode":"// pin and verify a single JDK before spawning instrumented JVMs\nPath java = Path.of(System.getenv(\"JAVA_HOME\"), \"bin\", \"java\");\nif (Files.notExists(java)) throw new IllegalStateException(\"JAVA_HOME misconfigured: \" + java);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin one JDK distribution/version in builds and runtime images","Never copy individual native libraries (libinstrument.so) between JDK installations"],"tags":["java-instrument","native","jni","version-mismatch","jvm-startup"],"backgroundTag":null,"analyzedSha":"88dfb74bbeefcf2b0aa11835183bcd949998fc8f","analyzedAt":"2026-08-14T11:45:09.665Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}