{"record":{"id":"0cc6a2f75e52ce47","repo":"elastic/elasticsearch","slug":"directory-for-entitlement-jar-does-not-exist","errorCode":null,"errorMessage":"Directory for entitlement jar does not exist: {}","messagePattern":"Directory for entitlement jar does not exist: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java","lineNumber":171,"sourceCode":"\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\"));\n        Path dir = esHome.resolve(\"lib/entitlement-agent\");\n        if (Files.exists(dir) == false) {\n            throw new IllegalStateException(\"Directory for entitlement jar does not exist: \" + dir);\n        }\n        try (var s = Files.list(dir)) {\n            var candidates = s.limit(2).toList();\n            if (candidates.size() != 1) {\n                throw new IllegalStateException(\"Expected one jar in \" + dir + \"; found \" + candidates.size());\n            }\n            return candidates.get(0).toString();\n        } catch (IOException e) {\n            throw new IllegalStateException(\"Failed to list entitlement jars in: \" + dir, e);\n        }\n    }\n\n    private static PolicyManager createPolicyManager(\n        Map<String, Policy> pluginPolicies,\n        PathLookup pathLookup,\n        Policy serverPolicyPatch,\n        Function<Class<?>, PolicyManager.PolicyScope> scopeResolver,\n        Map<String, Collection<Path>> pluginSourcePathsResolver","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java#L153-L189","documentation":"Thrown by EntitlementBootstrap.findAgentJar when the 'lib/entitlement-agent' directory under ES_HOME does not exist on the filesystem. The bootstrap resolves the directory from the 'es.path.home' system property and expects exactly one agent jar there. A missing directory means the distribution is incomplete or misconfigured.","triggerScenarios":"es.path.home resolves to a path whose 'lib/entitlement-agent' subdirectory fails Files.exists(); thrown before any attempt to list jars. Occurs when ES_HOME points at a partial/incorrect install.","commonSituations":"ES_HOME environment variable or es.path.home property points at the wrong directory; the distribution was extracted incompletely; a custom packaging omitted the entitlement-agent directory; running from a source tree without assembling the distribution.","solutions":["Verify ES_HOME points at a complete, freshly extracted distribution: 'ls $ES_HOME/lib/entitlement-agent'.","Re-download and re-extract the official distribution so lib/entitlement-agent is present.","If you set es.path.home explicitly, point it at the real distribution root.","Set -Des.entitlement.agentJar=<absolute path> to bypass directory discovery and name the jar directly."],"exampleFix":"// before: -Des.path.home=/opt/es-incomplete (missing lib/entitlement-agent)\n\n// after: point at a complete install, or name the jar directly\n-Des.path.home=/opt/elasticsearch-9.0.0\n// or\n-Des.entitlement.agentJar=/opt/elasticsearch-9.0.0/lib/entitlement-agent/entitlement-agent.jar","handlingStrategy":"validation","validationCode":"// Before bootstrap, verify the agent dir\nPath dir = Path.of(System.getProperty(\"es.path.home\")).resolve(\"lib/entitlement-agent\");\nif (!Files.isDirectory(dir)) {\n  throw new IllegalStateException(\"Missing \" + dir + \"; check ES_HOME or set es.entitlement.agentJar\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Point es.path.home at a complete, freshly extracted distribution.","Set -Des.entitlement.agentJar=<path> for non-standard layouts."],"tags":["entitlement","agent","path-validation","distribution","startup"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}