elastic/elasticsearch · critical · IllegalStateException

Expected one jar in {}; found {}

Error message

Expected one jar in {}; found {}

What it means

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.

Source

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

        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"));
        Path dir = esHome.resolve("lib/entitlement-agent");
        if (Files.exists(dir) == false) {
            throw new IllegalStateException("Directory for entitlement jar does not exist: " + dir);
        }
        try (var s = Files.list(dir)) {
            var candidates = s.limit(2).toList();
            if (candidates.size() != 1) {
                throw new IllegalStateException("Expected one jar in " + dir + "; found " + candidates.size());
            }
            return candidates.get(0).toString();
        } catch (IOException e) {
            throw new IllegalStateException("Failed to list entitlement jars in: " + dir, e);
        }
    }

    private static PolicyManager createPolicyManager(
        Map<String, Policy> pluginPolicies,
        PathLookup pathLookup,
        Policy serverPolicyPatch,
        Function<Class<?>, PolicyManager.PolicyScope> scopeResolver,
        Map<String, Collection<Path>> pluginSourcePathsResolver
    ) {
        FilesEntitlementsValidation.validate(pluginPolicies, pathLookup);

        return new PolicyManager(
            HardcodedEntitlements.serverPolicy(pathLookup.pidFile(), serverPolicyPatch),

View on GitHub (pinned to db6a809a66)

Solutions

1. List the directory: 'ls $ES_HOME/lib/entitlement-agent' and remove all but the single expected agent jar.
2. Reinstall the distribution so exactly one entitlement-agent jar is present.
3. Set -Des.entitlement.agentJar=<absolute path> to name the correct jar explicitly, bypassing the count check.

Example fix

// before: lib/entitlement-agent contains agent.jar AND agent-old.jar

// after: keep one, or name it explicitly
rm $ES_HOME/lib/entitlement-agent/agent-old.jar
# or
-Des.entitlement.agentJar=/abs/path/agent.jar

// Before bootstrap, assert exactly one jar
Path dir = Path.of(System.getProperty("es.path.home")).resolve("lib/entitlement-agent");
try (var s = Files.list(dir)) {
  long n = s.count();
  if (n != 1) throw new IllegalStateException("Expected 1 agent jar in " + dir + ", found " + n);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Directory for entitlement jar does not exist: {}
• Directory for entitlement bridge jar does not exist: ${dir}
• user.home system property is required
• Unable to attach entitlement agent [{}] after [{}ms]
• Failed to list entitlement jars in: {}

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