openjdk/jdk · error

java.lang.instrument/-javaagent: unknown error\n

Error message

java.lang.instrument/-javaagent: unknown error\n

What it means

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.

Source

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

    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 */

/*
 *  This will be called once each time a tool attaches to the VM and loads
 *  the JPLIS library.

View on GitHub (pinned to 88dfb74bbe)

Solutions

1. Verify JAVA_HOME and PATH point to a single consistent JDK installation (no mixed JDK copies)
2. Re-run with -Xlog:library=info to see which native libraries load and from where
3. If using a custom-built JDK or agent, rebuild the instrument module against the exact JVM it runs on
4. Check the JVM release notes for new init error codes if the error appears after a JDK upgrade

Example fix

# before: mixed JDKs
export JAVA_HOME=/opt/jdk21 PATH=/opt/jdk17/bin:$PATH
# after
export JAVA_HOME=/opt/jdk21 PATH=$JAVA_HOME/bin:$PATH

// pin and verify a single JDK before spawning instrumented JVMs
Path java = Path.of(System.getenv("JAVA_HOME"), "bin", "java");
if (Files.notExists(java)) throw new IllegalStateException("JAVA_HOME misconfigured: " + java);

When it happens

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

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

Related errors

• java.lang.instrument/-javaagent: allocation failure.\n
• Failed to retrieve atom name.
• -javaagent: memory allocation failure.\n
• -javaagent: memory allocation failed\n
• java.lang.instrument/-javaagent: cannot create native agent.

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