elastic/elasticsearch · critical · IllegalStateException

Failed to list entitlement jars in: {}

Error message

Failed to list entitlement jars in: {}

What it means

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.

Source

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

        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),
            HardcodedEntitlements.agentEntitlements(),
            pluginPolicies,
            scopeResolver,
            pluginSourcePathsResolver::get,

View on GitHub (pinned to db6a809a66)

Solutions

1. Check permissions on the directory: 'ls -ld $ES_HOME/lib/entitlement-agent' and ensure the ES user can read+execute it.
2. Confirm the path is actually a directory and not a file or broken symlink.
3. Remount or repair the underlying filesystem if a hardware/mount error is indicated by the cause.
4. Set -Des.entitlement.agentJar=<absolute path> to skip directory listing entirely.

Example fix

// before: directory not listable (permissions/mount)

// after: fix perms or bypass
chmod 755 $ES_HOME/lib/entitlement-agent
chown es:es $ES_HOME/lib/entitlement-agent
# or
-Des.entitlement.agentJar=/abs/path/agent.jar

// Pre-check readability
Path dir = Path.of(System.getProperty("es.path.home")).resolve("lib/entitlement-agent");
if (!Files.isReadable(dir)) throw new IllegalStateException("Cannot read " + dir);
if (!Files.isDirectory(dir)) throw new IllegalStateException("Not a directory: " + dir);

try {
  EntitlementBootstrap.initialize(...);
} catch (IllegalStateException e) {
  if (e.getCause() instanceof java.io.IOException io) {
    // filesystem-level: fix perms/mount, or set es.entitlement.agentJar
  }
  throw e;
}

When it happens

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

Common situations: Filesystem permissions deny listing the directory; the path is a file not a directory; a broken symlink; NFS/mount issues; disk I/O errors.

Related errors

• Failed to list entitlement jars in: ${dir}
• Failed to create parent directory '%s' when creating directo
• Failed to create directory '%s'
• Failed to list existing plugins
• could not remove the following files (in the order of attemp

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