{"record":{"id":"9a5128ff3b7f5e16","repo":"openjdk/jdk","slug":"agent-error-startfail","errorCode":"AGENT_ERROR_STARTFAIL","errorMessage":"Agent failed to start!\\n","messagePattern":"Agent failed to start!\\\\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/java.instrument/share/native/libinstrument/InvocationAdapter.c","lineNumber":448,"sourceCode":"        if (success) {\n            success = setLivePhaseEventHandlers(agent);\n            jplis_assert_msg(success, \"setLivePhaseEventHandlers failed\");\n        }\n\n        /*\n         * Start the agent\n         */\n        if (success) {\n            success = startJavaAgent(agent,\n                                     jni_env,\n                                     agentClass,\n                                     options,\n                                     agent->mAgentmainCaller);\n            jplis_assert_msg(success, \"startJavaAgent failed\");\n        }\n\n        if (!success) {\n            fprintf(stderr, \"Agent failed to start!\\n\");\n            result = AGENT_ERROR_STARTFAIL;\n        }\n\n        /*\n         * Clean-up\n         */\n        free(agentClass);\n        freeAttributes(attributes);\n    }\n\n    if (initerror != JPLIS_INIT_ERROR_NONE || result != JNI_OK) {\n        free(jarfile);\n    }\n    if (options != NULL) free(options);\n\n    return result;\n}\n","sourceCodeStart":430,"sourceCodeEnd":466,"githubUrl":"https://github.com/openjdk/jdk/blob/88dfb74bbeefcf2b0aa11835183bcd949998fc8f/src/java.instrument/share/native/libinstrument/InvocationAdapter.c#L430-L466","documentation":"Attach-path error (AGENT_ERROR_STARTFAIL = 102): the agent jar was accepted, but startJavaAgent failed — the agentmain method could not be invoked, was missing, threw an exception, or the JVM could not find/link the class. Attach completes with AgentInitializationException(102) and the message is printed to the target JVM's stderr.","triggerScenarios":"agentmain throws an exception; agentmain signature wrong (not public static, wrong args); agent class fails to link (NoClassDefFoundError for its dependencies missing from the agent jar); static initializer of the agent class fails.","commonSituations":"Agent jar without shaded dependencies (NoClassDefFoundError inside agentmain); attach-time API misuse where the agent assumes instrumentation capabilities not enabled (Can-Retransform-Classes false); version mismatch between agent and target JVM APIs.","solutions":["Read the exception printed to the target process's stderr/agent log — the underlying Java exception details appear there","Ensure the agent class exposes public static void agentmain(String args, Instrumentation inst)","Shade the agent's dependencies into the agent jar so agentmain can link","Declare required manifest capabilities (Can-Redefine-Classes, Can-Retransform-Classes, Can-Set-Native-Method-Prefix) for what agentmain does","Wrap agentmain body in try/catch and log rather than propagate, so partial failures are diagnosable"],"exampleFix":"// before\npublic static void agentmain(String args, Instrumentation inst) {\n    inst.retransformClasses(Target.class); // throws, attach fails\n}\n// after\npublic static void agentmain(String args, Instrumentation inst) {\n    try { inst.retransformClasses(Target.class); }\n    catch (Throwable t) { t.printStackTrace(); }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    vm.loadAgent(agentPath, opts);\n} catch (AgentInitializationException e) {\n    if (e.returnValue() == 102) {\n        // STARTFAIL: inspect target JVM stderr for the underlying agentmain exception\n        log.error(\"agentmain failed; check target stderr\", e);\n    }\n} catch (AgentLoadException e) {\n    log.error(\"agent transport failed\", e);\n}","preventionTips":["Make agentmain catch-and-log internally so failures are visible, not just fatal","Shade all agent dependencies into the agent jar","Test attach against a staging JVM with the same flags before production"],"tags":["java-instrument","attach-api","agentmain","agent-error-startfail","diagnostics"],"backgroundTag":null,"analyzedSha":"88dfb74bbeefcf2b0aa11835183bcd949998fc8f","analyzedAt":"2026-08-14T11:45:09.665Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}