java.lang.instrument/-javaagent: cannot create native agent.

Error message

java.lang.instrument/-javaagent: cannot create native agent.\n

What it means

createNewJPLISAgent() returned JPLIS_INIT_ERROR_CANNOT_CREATE_NATIVE_AGENT — the native JPLISAgent structure (agent state, JNI environment bookkeeping, transform callbacks) could not be allocated/initialized. The launcher maps this enum to JNI_ERR and prints this line. It is the 'cannot even build the native agent object' failure, before any Java agent class is loaded.

Source

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

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

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

    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;
    }

View on GitHub (pinned to 88dfb74bbe)

Solutions

Free memory / raise container limits and retry the JVM start
If embedding the JVM, ensure you pass agent options via JavaVMInitOptions properly and the VM is fully created before agent hooks run
Test with the stock 'java' launcher to isolate custom-launcher issues
Update the JDK — initialization paths in libinstrument have seen fixes across releases

Defensive patterns

Strategy: validation

Prevention

Ensure adequate memory before launching with -javaagent
Embedders: create the VM via JNI_CreateJavaVM with proper options before agent hooks run
Test the exact agent+JDK combination in CI

When it happens

Trigger: Internal allocation of the JPLISAgent or its dependent structures failing (OOM at startup), or environment/JNI state being invalid when -javaagent processing runs (unusual VM configurations, agents loaded in nested/foreign launchers that do not provide a proper JNIEnv). The switch in DEF_Agent_OnLoad maps this specific enum constant.

Common situations: Memory-exhausted hosts/containers at JVM start; custom launchers (embedded JVM via JNI_CreateJavaVM) that pass -javaagent options without a fully initialized VM; malformed embedding that violates the JNI invocation contract. Rare in standard 'java' launcher usage.

Related errors

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