What causes "Agent failed to start!\n" in openjdk/jdk?

Read the exception printed to the target process's stderr/agent log — the underlying Java exception details appear there

openjdk/jdk · error

AGENT_ERROR_STARTFAIL

AGENT_ERROR_STARTFAIL

Error message

Agent failed to start!\n

What it means

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.

Source

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

        if (success) {
            success = setLivePhaseEventHandlers(agent);
            jplis_assert_msg(success, "setLivePhaseEventHandlers failed");
        }

        /*
         * Start the agent
         */
        if (success) {
            success = startJavaAgent(agent,
                                     jni_env,
                                     agentClass,
                                     options,
                                     agent->mAgentmainCaller);
            jplis_assert_msg(success, "startJavaAgent failed");
        }

        if (!success) {
            fprintf(stderr, "Agent failed to start!\n");
            result = AGENT_ERROR_STARTFAIL;
        }

        /*
         * Clean-up
         */
        free(agentClass);
        freeAttributes(attributes);
    }

    if (initerror != JPLIS_INIT_ERROR_NONE || result != JNI_OK) {
        free(jarfile);
    }
    if (options != NULL) free(options);

    return result;
}

View on GitHub (pinned to 88dfb74bbe)

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

Example fix

// before
public static void agentmain(String args, Instrumentation inst) {
    inst.retransformClasses(Target.class); // throws, attach fails
}
// after
public static void agentmain(String args, Instrumentation inst) {
    try { inst.retransformClasses(Target.class); }
    catch (Throwable t) { t.printStackTrace(); }
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    vm.loadAgent(agentPath, opts);
} catch (AgentInitializationException e) {
    if (e.returnValue() == 102) {
        // STARTFAIL: inspect target JVM stderr for the underlying agentmain exception
        log.error("agentmain failed; check target stderr", e);
    }
} catch (AgentLoadException e) {
    log.error("agent transport failed", e);
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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