elastic/elasticsearch · critical · IllegalStateException

Directory for entitlement jar does not exist: {}

Error message

Directory for entitlement jar does not exist: {}

What it means

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.

Source

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

    private static void exportInitializationToAgent() {
        String initPkg = EntitlementInitialization.class.getPackageName();
        // agent will live in unnamed module
        Module unnamedModule = ClassLoader.getSystemClassLoader().getUnnamedModule();
        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

View on GitHub (pinned to db6a809a66)

Solutions

1. Verify ES_HOME points at a complete, freshly extracted distribution: 'ls $ES_HOME/lib/entitlement-agent'.
2. Re-download and re-extract the official distribution so lib/entitlement-agent is present.
3. If you set es.path.home explicitly, point it at the real distribution root.
4. Set -Des.entitlement.agentJar=<absolute path> to bypass directory discovery and name the jar directly.

Example fix

// before: -Des.path.home=/opt/es-incomplete (missing lib/entitlement-agent)

// after: point at a complete install, or name the jar directly
-Des.path.home=/opt/elasticsearch-9.0.0
// or
-Des.entitlement.agentJar=/opt/elasticsearch-9.0.0/lib/entitlement-agent/entitlement-agent.jar

// Before bootstrap, verify the agent dir
Path dir = Path.of(System.getProperty("es.path.home")).resolve("lib/entitlement-agent");
if (!Files.isDirectory(dir)) {
  throw new IllegalStateException("Missing " + dir + "; check ES_HOME or set es.entitlement.agentJar");
}

When it happens

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

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

Related errors

• Expected one jar in {}; found {}
• Can not start {}, is not a directory: {}
• Can't run bin script: `{}` does not exist. Is this the distr
• Directory for entitlement bridge jar does not exist: ${dir}
• user.home system property is required

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