{"record":{"id":"892858cab0441a91","repo":"elastic/elasticsearch","slug":"expected-one-jar-in-found","errorCode":null,"errorMessage":"Expected one jar in {}; found {}","messagePattern":"Expected one jar in (.+?); found (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java","lineNumber":176,"sourceCode":"        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\n    ) {\n        FilesEntitlementsValidation.validate(pluginPolicies, pathLookup);\n\n        return new PolicyManager(\n            HardcodedEntitlements.serverPolicy(pathLookup.pidFile(), serverPolicyPatch),","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java#L158-L194","documentation":"Thrown by EntitlementBootstrap.findAgentJar when the 'lib/entitlement-agent' directory does not contain exactly one JAR file. The code lists the directory with a limit of 2 entries; if the count is not 1 (zero, two, or more) it refuses to guess which jar is the agent. This enforces a strict single-artifact contract for the entitlement agent.","triggerScenarios":"Files.list(dir) with limit(2) yields a list whose size() != 1. Either the directory is empty (0) or it contains 2+ jars. Triggered after the directory-existence check passes.","commonSituations":"A packaging bug dropped multiple versions of the agent jar into the directory; a stale jar from a previous version remained after upgrade; the directory was emptied by a failed install; a manual copy added a second jar.","solutions":["List the directory: 'ls $ES_HOME/lib/entitlement-agent' and remove all but the single expected agent jar.","Reinstall the distribution so exactly one entitlement-agent jar is present.","Set -Des.entitlement.agentJar=<absolute path> to name the correct jar explicitly, bypassing the count check."],"exampleFix":"// before: lib/entitlement-agent contains agent.jar AND agent-old.jar\n\n// after: keep one, or name it explicitly\nrm $ES_HOME/lib/entitlement-agent/agent-old.jar\n# or\n-Des.entitlement.agentJar=/abs/path/agent.jar","handlingStrategy":"validation","validationCode":"// Before bootstrap, assert exactly one jar\nPath dir = Path.of(System.getProperty(\"es.path.home\")).resolve(\"lib/entitlement-agent\");\ntry (var s = Files.list(dir)) {\n  long n = s.count();\n  if (n != 1) throw new IllegalStateException(\"Expected 1 agent jar in \" + dir + \", found \" + n);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clean the entitlement-agent directory before reinstalling a distribution.","Set -Des.entitlement.agentJar=<path> to bypass the single-jar check."],"tags":["entitlement","agent","packaging","path-validation","startup"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}