elastic/elasticsearch · critical · IllegalStateException

Unable to attach entitlement agent [{}] after [{}ms]

Error message

Unable to attach entitlement agent [{}] after [{}ms]

What it means

Thrown by EntitlementBootstrap.loadAgent when the Java instrumentation agent (the entitlement agent jar) cannot be attached to the running JVM. Attachment can fail with AttachNotSupportedException, IOException, AgentLoadException, or AgentInitializationException; all are wrapped into an IllegalStateException naming the agent path and elapsed milliseconds. The entitlement system cannot function without the agent, so this is fatal.

Source

Thrown at libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java:150

        long startMillis = System.currentTimeMillis();
        try {
            VirtualMachine vm = VirtualMachine.attach(Long.toString(ProcessHandle.current().pid()));
            long attachedMillis = System.currentTimeMillis();
            try {
                vm.loadAgent(agentPath, entitlementInitializationClassName);
            } finally {
                vm.detach();
            }
            long doneMillis = System.currentTimeMillis();
            logger.info(
                "Entitlement agent attached in [{}ms] (attach=[{}ms], loadAgent+detach=[{}ms])",
                doneMillis - startMillis,
                attachedMillis - startMillis,
                doneMillis - attachedMillis
            );
        } catch (AttachNotSupportedException | IOException | AgentLoadException | AgentInitializationException e) {
            long elapsedMillis = System.currentTimeMillis() - startMillis;
            throw new IllegalStateException("Unable to attach entitlement agent [" + agentPath + "] after [" + elapsedMillis + "ms]", e);
        }
    }

    private static void exportInitializationToAgent() {
        String initPkg = EntitlementInitialization.class.getPackageName();
        // agent will live in unnamed module
        Module unnamedModule = ClassLoader.getSystemClassLoader().getUnnamedModule();
        EntitlementInitialization.class.getModule().addExports(initPkg, unnamedModule);
    }

    static String findAgentJar() {
        String propertyName = "es.entitlement.agentJar";
        String propertyValue = System.getProperty(propertyName);
        if (propertyValue != null) {
            return propertyValue;
        }

        Path esHome = Path.of(System.getProperty("es.path.home"));

View on GitHub (pinned to db6a809a66)

Solutions

1. Run a full JDK (not a stripped JRE) that includes the jdk.attach module.
2. Ensure dynamic attach is not disabled: remove any -XX:+DisableAttachMechanism flag.
3. If running in a container, run with sufficient privileges or configure the runtime to allow self-attach (same PID namespace, no seccomp denial of ptrace).
4. Verify the agent jar path named in the message exists and is readable by the ES process.

Example fix

// before: java -XX:+DisableAttachMechanism -jar es.jar

// after: allow attach
java -jar es.jar
// and ensure a JDK with jdk.attach is on PATH/JAVA_HOME

// Probe attach support before bootstrap
try {
  Class.forName("com.sun.tools.attach.VirtualMachine");
} catch (ClassNotFoundException e) {
  throw new IllegalStateException("jdk.attach module missing; use a full JDK", e);
}

try {
  EntitlementBootstrap.initialize(...);
} catch (IllegalStateException e) {
  if (e.getMessage().contains("Unable to attach entitlement agent")) {
    // surface to operator: need full JDK + attach enabled + container perms
    throw new IllegalStateException("Entitlement agent attach failed; check JDK and container attach permissions", e);
  }
  throw e;
}

When it happens

Trigger: VirtualMachine.attach(...) or vm.loadAgent(...) throws one of the four attachment exceptions. Common when running in a JVM/container where dynamic agent attachment is disabled, the tools.jar/attach module is absent, or a security manager blocks com.sun.tools.attach.

Common situations: Running inside a container that disabled JVM attach (e.g. -XX:+DisableAttachMechanism); a JRE (not JDK) without the jdk.attach module; a SecurityManager or OS AppArmor/SELinux denying ptrace/attach; PID namespace issues preventing self-attach in some containers.

Related errors

• Failed to transform JDK classes for entitlements
• Directory for entitlement jar does not exist: {}
• Expected one jar in {}; found {}
• Failed to list entitlement jars in: {}
• Directory for entitlement bridge jar does not exist: ${dir}

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/32958b1be446fcbc. Report an issue: GitHub.