elastic/elasticsearch · error · IOException

Plugins directory missing: {pluginsDir}

Error message

Plugins directory missing: {pluginsDir}

What it means

Thrown by ListPluginsCommand.execute (an IOException, not a UserException) when env.pluginsDir() does not exist on disk at the moment the `list` CLI command runs. The command refuses to enumerate a missing plugins directory rather than silently printing an empty list. No exit code is attached because it is a raw IOException surfaced by the CLI harness.

Source

Thrown at distribution/tools/plugin-cli/src/main/java/org/elasticsearch/plugins/cli/ListPluginsCommand.java:44

import java.util.Collections;
import java.util.List;
import java.util.Objects;

import static org.elasticsearch.plugins.cli.SyncPluginsAction.ELASTICSEARCH_PLUGINS_YML_CACHE;

/**
 * A command for the plugin cli to list plugins installed in elasticsearch.
 */
class ListPluginsCommand extends EnvironmentAwareCommand {

    ListPluginsCommand() {
        super("Lists installed elasticsearch plugins");
    }

    @Override
    public void execute(Terminal terminal, OptionSet options, Environment env, ProcessInfo processInfo) throws Exception {
        if (Files.exists(env.pluginsDir()) == false) {
            throw new IOException("Plugins directory missing: " + env.pluginsDir());
        }

        terminal.println(Terminal.Verbosity.VERBOSE, "Plugins directory: " + env.pluginsDir());
        final List<Path> plugins = new ArrayList<>();
        try (DirectoryStream<Path> paths = Files.newDirectoryStream(env.pluginsDir())) {
            for (Path path : paths) {
                if (path.getFileName().toString().equals(ELASTICSEARCH_PLUGINS_YML_CACHE) == false) {
                    plugins.add(path);
                }
            }
        }
        Collections.sort(plugins);
        for (final Path plugin : plugins) {
            printPlugin(env, terminal, plugin, "");
        }
    }

    private static void printPlugin(Environment env, Terminal terminal, Path plugin, String prefix) throws IOException {

View on GitHub (pinned to db6a809a66)

Solutions

1. Verify the plugins directory path: check `path.plugins` in elasticsearch.yml and the default ES_HOME/plugins.
2. Recreate the directory if it was deleted: `mkdir -p <ES_HOME>/plugins`.
3. Run the CLI from the correct ES_HOME so env.pluginsDir() resolves to the real distribution plugins dir.

Example fix

# before: ES_PATH_CONF points at /etc/elasticsearch but plugins/ is under /usr/share/elasticsearch
export ES_HOME=/usr/share/elasticsearch
# after: invoke from the real install root
$ES_HOME/bin/elasticsearch-plugin list

// Before listing, confirm the plugins dir is present.
Path plugins = env.pluginsDir();
if (!Files.exists(plugins)) {
    throw new FileNotFoundException("Plugins dir missing: " + plugins);
}

When it happens

Trigger: Running `elasticsearch-plugin list` (or any code path calling ListPluginsCommand.execute) on a node whose ES_HOME/plugins (or configured path.plugins) has not been created — e.g. before first run, after a partial cleanup, or with a misconfigured ES_PATH_CONF / path.plugins.

Common situations: Fresh extraction where the distribution's plugins/ dir was deleted; pointing ES_PATH_CONF at a non-existent config root; container image that pruned the plugins directory; running the plugin CLI from the wrong working directory so path resolution lands on a missing dir.

Related errors

• 74
• CONFIG
• Can't determine OS from: ${os}
• Unable to create reaper JAR output directory {}
• Failed to write unicast_hosts for {}

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