elastic/elasticsearch · error · UserException

78

78

Error message

Can only use [elasticsearch-plugins.yml] config file with distribution type [docker]

What it means

Thrown by SyncPluginsCliProvider when elasticsearch-plugins.yml exists in the config dir but the running build is not the Docker distribution type. The plugins.yml sync mechanism is a Docker-only feature baked into the Docker entrypoint; other distributions are expected to use the elasticsearch-plugin CLI manually.

Source

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

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

public class SyncPluginsCliProvider implements CliToolProvider {
    @Override
    public String name() {
        return "sync-plugins";
    }

    @Override
    public Command create() {
        return new EnvironmentAwareCommand("sync installed plugins from elasticsearch-plugins.yml") {
            @Override
            public void execute(Terminal terminal, OptionSet options, Environment env, ProcessInfo processInfo) throws Exception {
                var action = new SyncPluginsAction(terminal, env);
                if (Files.exists(env.configDir().resolve(ELASTICSEARCH_PLUGINS_YML)) == false) {
                    return;
                }
                if (Build.current().type() != Build.Type.DOCKER) {
                    throw new UserException(
                        ExitCodes.CONFIG,
                        "Can only use [elasticsearch-plugins.yml] config file with distribution type [docker]"
                    );
                }
                try {
                    action.execute();
                } catch (PluginSyncException e) {
                    throw new UserException(ExitCodes.CONFIG, ELASTICSEARCH_PLUGINS_YML + ": " + e.getMessage());
                }
            }
        };
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Remove elasticsearch-plugins.yml from ES_HOME/config/ if running a non-Docker distribution.
2. Switch to the official Docker image if you want declarative plugin sync.
3. Install plugins manually with bin/elasticsearch-plugin install <name> on tar/rpm/deb distributions.

Example fix

# before (tar distribution with docker-style config)
ls config/elasticsearch-plugins.yml  # exists -> error

# after
rm config/elasticsearch-plugins.yml
bin/elasticsearch-plugin install analysis-icu

Path yml = env.configDir().resolve("elasticsearch-plugins.yml");
if (Files.exists(yml) && Build.current().type() != Build.Type.DOCKER) {
    throw new IllegalStateException(
        "elasticsearch-plugins.yml is Docker-only; remove it or switch to the Docker image.");
}

When it happens

Trigger: A non-Docker ES build (tar, zip, rpm, deb) starts up and finds config/elasticsearch-plugins.yml — the provider refuses to process it.

Common situations: Copying a Docker image's elasticsearch-plugins.yml into a tar-distribution config dir; running from source or a local build with a leftover config file; migrating config from Docker to a VM deployment.

Related errors

• Plugins directory missing: {pluginsDir}
• Could not write config file: {}
• Cannot set Elasticsearch Distribution type to ${type}. Type
• distribution type [${typeName}] for elasticsearch distributi
• platform cannot be set on elasticsearch distribution [${name

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