{"record":{"id":"637d65ad18d477e3","repo":"elastic/elasticsearch","slug":"failed-to-list-entitlement-jars-in","errorCode":null,"errorMessage":"Failed to list entitlement jars in: {}","messagePattern":"Failed to list entitlement jars in: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java","lineNumber":180,"sourceCode":"        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\n    ) {\n        FilesEntitlementsValidation.validate(pluginPolicies, pathLookup);\n\n        return new PolicyManager(\n            HardcodedEntitlements.serverPolicy(pathLookup.pidFile(), serverPolicyPatch),\n            HardcodedEntitlements.agentEntitlements(),\n            pluginPolicies,\n            scopeResolver,\n            pluginSourcePathsResolver::get,","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java#L162-L198","documentation":"Thrown by EntitlementBootstrap.findAgentJar when Files.list(dir) throws IOException while trying to enumerate the entitlement-agent directory. The underlying IOException is wrapped as the cause of an IllegalStateException naming the directory. This is an I/O-level failure (permissions, broken symlink, FS error) rather than a logic error.","triggerScenarios":"Files.list on the entitlement-agent directory throws IOException (e.g. NotDirectoryException, AccessDeniedException, or a low-level I/O error). The catch block wraps it into IllegalStateException.","commonSituations":"Filesystem permissions deny listing the directory; the path is a file not a directory; a broken symlink; NFS/mount issues; disk I/O errors.","solutions":["Check permissions on the directory: 'ls -ld $ES_HOME/lib/entitlement-agent' and ensure the ES user can read+execute it.","Confirm the path is actually a directory and not a file or broken symlink.","Remount or repair the underlying filesystem if a hardware/mount error is indicated by the cause.","Set -Des.entitlement.agentJar=<absolute path> to skip directory listing entirely."],"exampleFix":"// before: directory not listable (permissions/mount)\n\n// after: fix perms or bypass\nchmod 755 $ES_HOME/lib/entitlement-agent\nchown es:es $ES_HOME/lib/entitlement-agent\n# or\n-Des.entitlement.agentJar=/abs/path/agent.jar","handlingStrategy":"try-catch","validationCode":"// Pre-check readability\nPath dir = Path.of(System.getProperty(\"es.path.home\")).resolve(\"lib/entitlement-agent\");\nif (!Files.isReadable(dir)) throw new IllegalStateException(\"Cannot read \" + dir);\nif (!Files.isDirectory(dir)) throw new IllegalStateException(\"Not a directory: \" + dir);","typeGuard":null,"tryCatchPattern":"try {\n  EntitlementBootstrap.initialize(...);\n} catch (IllegalStateException e) {\n  if (e.getCause() instanceof java.io.IOException io) {\n    // filesystem-level: fix perms/mount, or set es.entitlement.agentJar\n  }\n  throw e;\n}","preventionTips":["Ensure the ES process owns and can list lib/entitlement-agent.","Avoid symlinks into unmounted/network filesystems for the agent dir."],"tags":["entitlement","agent","io","permissions","filesystem"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T08:17:17.861Z"}