elastic/elasticsearch · critical · UserException

70

70

Error message

Expected to find [apm] module in [{apmModule}]! Installation is corrupt

What it means

Thrown by APMJvmOptions.findAgentJar() when the modules/apm directory does not exist on a production release. The apm module ships the elastic-apm-agent jar that ES attaches as a javaagent; its absence on a production build means the installation is corrupt.

Source

Thrown at distribution/tools/server-cli/src/main/java/org/elasticsearch/server/cli/APMJvmOptions.java:362

            p.store(os, " Automatically generated by Elasticsearch, do not edit!");
        }

        return tmpFile;
    }

    /**
     * The JVM argument that configure the APM agent needs to specify the agent jar path, so this method
     * finds the jar by inspecting the filesystem.
     * @return the agent jar file
     * @throws IOException if a problem occurs reading the filesystem
     */
    @Nullable
    static Path findAgentJar(String installDir) throws IOException, UserException {
        final Path apmModule = Path.of(installDir).resolve("modules").resolve("apm");

        if (Files.notExists(apmModule)) {
            if (Build.current().isProductionRelease()) {
                throw new UserException(
                    ExitCodes.CODE_ERROR,
                    "Expected to find [apm] module in [" + apmModule + "]! Installation is corrupt"
                );
            }
            return null;
        }

        try (var apmStream = Files.list(apmModule)) {
            final List<Path> paths = apmStream.filter(
                path -> path.getFileName().toString().matches("elastic-apm-agent-java8-\\d+\\.\\d+\\.\\d+\\.jar")
            ).toList();

            if (paths.size() > 1) {
                throw new UserException(
                    ExitCodes.CODE_ERROR,
                    "Found multiple [elastic-apm-agent] jars under [" + apmModule + "]! Installation is corrupt."
                );
            }

View on GitHub (pinned to db6a809a66)

Solutions

1. Reinstall/re-extract Elasticsearch from the official archive so modules/apm is present.
2. If you intentionally strip the apm module, build a non-production release instead.
3. ls $ES_HOME/modules/apm — it must contain elastic-apm-agent-java8-*.jar.

Path apmModule = Path.of(installDir).resolve("modules").resolve("apm");
if (Build.current().isProductionRelease() && Files.notExists(apmModule)) {
    throw new IllegalStateException("modules/apm missing — reinstall Elasticsearch.");
}

When it happens

Trigger: Production release (Build.current().isProductionRelease() is true) and Path(installDir)/modules/apm does not exist. On non-production builds the method returns null instead.

Common situations: Someone deleted or never extracted modules/apm; a custom Docker image stripped the apm module; a repackaged distribution omitted it; partial extraction of the archive.

Related errors

• Missing procrun exe: ${procrun}
• Unable to create reaper JAR output directory {}
• Failed to write unicast_hosts for {}
• Can not start {}, is not a directory: {}
• Failed to create working directory for {}, with: {}

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