{"record":{"id":"9f780aa4390453e6","repo":"elastic/elasticsearch","slug":"78-9f780a","errorCode":"78","errorMessage":"Can only use [elasticsearch-plugins.yml] config file with distribution type [docker]","messagePattern":"Can only use \\[elasticsearch-plugins\\.yml\\] config file with distribution type \\[docker\\]","errorType":"exception","errorClass":"UserException","httpStatus":null,"severity":"error","filePath":"distribution/tools/plugin-cli/src/main/java/org/elasticsearch/plugins/cli/SyncPluginsCliProvider.java","lineNumber":44,"sourceCode":"import static org.elasticsearch.plugins.cli.SyncPluginsAction.ELASTICSEARCH_PLUGINS_YML;\n\npublic class SyncPluginsCliProvider implements CliToolProvider {\n    @Override\n    public String name() {\n        return \"sync-plugins\";\n    }\n\n    @Override\n    public Command create() {\n        return new EnvironmentAwareCommand(\"sync installed plugins from elasticsearch-plugins.yml\") {\n            @Override\n            public void execute(Terminal terminal, OptionSet options, Environment env, ProcessInfo processInfo) throws Exception {\n                var action = new SyncPluginsAction(terminal, env);\n                if (Files.exists(env.configDir().resolve(ELASTICSEARCH_PLUGINS_YML)) == false) {\n                    return;\n                }\n                if (Build.current().type() != Build.Type.DOCKER) {\n                    throw new UserException(\n                        ExitCodes.CONFIG,\n                        \"Can only use [elasticsearch-plugins.yml] config file with distribution type [docker]\"\n                    );\n                }\n                try {\n                    action.execute();\n                } catch (PluginSyncException e) {\n                    throw new UserException(ExitCodes.CONFIG, ELASTICSEARCH_PLUGINS_YML + \": \" + e.getMessage());\n                }\n            }\n        };\n    }\n}\n","sourceCodeStart":26,"sourceCodeEnd":58,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/distribution/tools/plugin-cli/src/main/java/org/elasticsearch/plugins/cli/SyncPluginsCliProvider.java#L26-L58","documentation":"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.","triggerScenarios":"A non-Docker ES build (tar, zip, rpm, deb) starts up and finds config/elasticsearch-plugins.yml — the provider refuses to process it.","commonSituations":"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.","solutions":["Remove elasticsearch-plugins.yml from ES_HOME/config/ if running a non-Docker distribution.","Switch to the official Docker image if you want declarative plugin sync.","Install plugins manually with bin/elasticsearch-plugin install <name> on tar/rpm/deb distributions."],"exampleFix":"# before (tar distribution with docker-style config)\nls config/elasticsearch-plugins.yml  # exists -> error\n\n# after\nrm config/elasticsearch-plugins.yml\nbin/elasticsearch-plugin install analysis-icu","handlingStrategy":"validation","validationCode":"Path yml = env.configDir().resolve(\"elasticsearch-plugins.yml\");\nif (Files.exists(yml) && Build.current().type() != Build.Type.DOCKER) {\n    throw new IllegalStateException(\n        \"elasticsearch-plugins.yml is Docker-only; remove it or switch to the Docker image.\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only put elasticsearch-plugins.yml in config/ for Docker deployments.","On non-Docker, prefer bin/elasticsearch-plugin install for plugin management.","Document the distribution type alongside the config in shared repos."],"tags":["plugins","docker","distribution","config"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}