openjdk/jdk · error

-javaagent: agent class not specified.\n

Error message

-javaagent: agent class not specified.\n

What it means

The instrument library could not determine which class to load as the agent: the JAR's manifest has no usable agent class attribute for the current path (Premain-Class at JVM launch, Agent-Class when attaching). JPLIS initialization returns JPLIS_INIT_ERROR_AGENT_CLASS_NOT_SPECIFIED and Agent_OnLoad returns JNI_ERR, failing JVM startup when given on the command line.

Source

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

    switch (initerror) {
    case JPLIS_INIT_ERROR_NONE:
      result = JNI_OK;
      break;
    case JPLIS_INIT_ERROR_CANNOT_CREATE_NATIVE_AGENT:
      result = JNI_ERR;
      fprintf(stderr, "java.lang.instrument/-javaagent: cannot create native agent.\n");
      break;
    case JPLIS_INIT_ERROR_FAILURE:
      result = JNI_ERR;
      fprintf(stderr, "java.lang.instrument/-javaagent: initialization of native agent failed.\n");
      break;
    case JPLIS_INIT_ERROR_ALLOCATION_FAILURE:
      result = JNI_ERR;
      fprintf(stderr, "java.lang.instrument/-javaagent: allocation failure.\n");
      break;
    case JPLIS_INIT_ERROR_AGENT_CLASS_NOT_SPECIFIED:
      result = JNI_ERR;
      fprintf(stderr, "-javaagent: agent class not specified.\n");
      break;
    default:
      result = JNI_ERR;
      fprintf(stderr, "java.lang.instrument/-javaagent: unknown error\n");
      break;
    }
    return result;
}

/*
 * Agent_OnAttach returns a jint. 0/JNI_OK indicates success and non-0
 * indicates an error. To allow the attach mechanism throw an
 * AgentInitializationException with a reasonable exception message we define
 * a few specific errors here.
 */
#define AGENT_ERROR_BADJAR    ((jint)100)  /* Agent JAR not found or no Agent-Class attribute */
#define AGENT_ERROR_NOTONCP   ((jint)101)  /* Unable to add JAR file to system class path */
#define AGENT_ERROR_STARTFAIL ((jint)102)  /* No agentmain method or agentmain failed */

View on GitHub (pinned to 88dfb74bbe)

Solutions

1. Unzip the agent jar and inspect META-INF/MANIFEST.MF: unzip -p agent.jar META-INF/MANIFEST.MF
2. Add 'Premain-Class: com.example.Agent' for load-time agents (and 'Agent-Class: com.example.Agent' for attach-time) to the manifest main section
3. Configure the build to preserve/merge manifest attributes (e.g. maven-shade-plugin ManifestResourceTransformer, Gradle jar manifest block)
4. Verify the agent class has a valid public static premain(String, Instrumentation) (or agentmain) method

Example fix

// before: no manifest attributes
jar cf agent.jar -C classes .
// after
printf 'Premain-Class: com.example.Agent\nCan-Redefine-Classes: true\n' > mf.txt
jar cfm agent.jar mf.txt -C classes .

// validate an agent jar before putting it on the command line
try (JarFile jf = new JarFile("agent.jar")) {
    Manifest mf = jf.getManifest();
    if (mf == null || mf.getMainAttributes().getValue("Premain-Class") == null)
        throw new IllegalArgumentException("agent.jar lacks Premain-Class");
}

When it happens

Trigger: Launching with -javaagent:some.jar whose META-INF/MANIFEST.MF lacks Premain-Class; attaching at runtime to a jar lacking Agent-Class; a manifest that exists but with a misspelled attribute name or one placed outside the main section.

Common situations: Hand-built agent JARs where the manifest was overwritten by the build tool; fat/uber JARs repackaged with a new manifest; shading plugins stripping manifest attributes; typo 'PreMain-Class' instead of 'Premain-Class'.

Related errors

• Error opening zip file or JAR manifest missing : %s\n
• Failed to find Premain-Class manifest attribute in %s\n
• -javaagent: Premain-Class value is too big\n
• -javaagent: memory allocation failure.\n
• -javaagent: memory allocation failed\n

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