{"record":{"id":"32958b1be446fcbc","repo":"elastic/elasticsearch","slug":"unable-to-attach-entitlement-agent-after-m","errorCode":null,"errorMessage":"Unable to attach entitlement agent [{}] after [{}ms]","messagePattern":"Unable to attach entitlement agent \\[(.+?)\\] after \\[(.+?)ms\\]","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java","lineNumber":150,"sourceCode":"        long startMillis = System.currentTimeMillis();\n        try {\n            VirtualMachine vm = VirtualMachine.attach(Long.toString(ProcessHandle.current().pid()));\n            long attachedMillis = System.currentTimeMillis();\n            try {\n                vm.loadAgent(agentPath, entitlementInitializationClassName);\n            } finally {\n                vm.detach();\n            }\n            long doneMillis = System.currentTimeMillis();\n            logger.info(\n                \"Entitlement agent attached in [{}ms] (attach=[{}ms], loadAgent+detach=[{}ms])\",\n                doneMillis - startMillis,\n                attachedMillis - startMillis,\n                doneMillis - attachedMillis\n            );\n        } catch (AttachNotSupportedException | IOException | AgentLoadException | AgentInitializationException e) {\n            long elapsedMillis = System.currentTimeMillis() - startMillis;\n            throw new IllegalStateException(\"Unable to attach entitlement agent [\" + agentPath + \"] after [\" + elapsedMillis + \"ms]\", e);\n        }\n    }\n\n    private static void exportInitializationToAgent() {\n        String initPkg = EntitlementInitialization.class.getPackageName();\n        // agent will live in unnamed module\n        Module unnamedModule = ClassLoader.getSystemClassLoader().getUnnamedModule();\n        EntitlementInitialization.class.getModule().addExports(initPkg, unnamedModule);\n    }\n\n    static String findAgentJar() {\n        String propertyName = \"es.entitlement.agentJar\";\n        String propertyValue = System.getProperty(propertyName);\n        if (propertyValue != null) {\n            return propertyValue;\n        }\n\n        Path esHome = Path.of(System.getProperty(\"es.path.home\"));","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java#L132-L168","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run a full JDK (not a stripped JRE) that includes the jdk.attach module.","Ensure dynamic attach is not disabled: remove any -XX:+DisableAttachMechanism flag.","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).","Verify the agent jar path named in the message exists and is readable by the ES process."],"exampleFix":"// before: java -XX:+DisableAttachMechanism -jar es.jar\n\n// after: allow attach\njava -jar es.jar\n// and ensure a JDK with jdk.attach is on PATH/JAVA_HOME","handlingStrategy":"try-catch","validationCode":"// Probe attach support before bootstrap\ntry {\n  Class.forName(\"com.sun.tools.attach.VirtualMachine\");\n} catch (ClassNotFoundException e) {\n  throw new IllegalStateException(\"jdk.attach module missing; use a full JDK\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  EntitlementBootstrap.initialize(...);\n} catch (IllegalStateException e) {\n  if (e.getMessage().contains(\"Unable to attach entitlement agent\")) {\n    // surface to operator: need full JDK + attach enabled + container perms\n    throw new IllegalStateException(\"Entitlement agent attach failed; check JDK and container attach permissions\", e);\n  }\n  throw e;\n}","preventionTips":["Run a full JDK with the jdk.attach module present.","Do not pass -XX:+DisableAttachMechanism.","In containers, ensure the PID namespace and seccomp profile allow self-attach."],"tags":["entitlement","agent","instrumentation","jvm-attach","container"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}