{"record":{"id":"65793a07f2f76153","repo":"elastic/elasticsearch","slug":"plugins-directory-missing-pluginsdir-65793a","errorCode":null,"errorMessage":"Plugins directory missing: {pluginsDir}","messagePattern":"Plugins directory missing: (.+?)","errorType":"exception","errorClass":"PluginSyncException","httpStatus":null,"severity":"error","filePath":"distribution/tools/plugin-cli/src/main/java/org/elasticsearch/plugins/cli/SyncPluginsAction.java","lineNumber":91,"sourceCode":"        }\n    }\n\n    /**\n     * Synchronises plugins from the config file to the plugins dir.\n     *\n     * @throws Exception if anything goes wrong\n     */\n    public void execute() throws Exception {\n        final Path configPath = this.env.configDir().resolve(ELASTICSEARCH_PLUGINS_YML);\n        final Path previousConfigPath = this.env.pluginsDir().resolve(ELASTICSEARCH_PLUGINS_YML_CACHE);\n\n        if (Files.exists(configPath) == false) {\n            // The `PluginsManager` will have checked that this file exists before invoking the action.\n            throw new PluginSyncException(\"Plugins config does not exist: \" + configPath.toAbsolutePath());\n        }\n\n        if (Files.exists(env.pluginsDir()) == false) {\n            throw new PluginSyncException(\"Plugins directory missing: \" + env.pluginsDir());\n        }\n\n        // Parse descriptor file\n        final PluginsConfig pluginsConfig = PluginsConfig.parseConfig(configPath, YamlXContent.yamlXContent);\n        pluginsConfig.validate(InstallPluginAction.OFFICIAL_PLUGINS, InstallPluginAction.PLUGINS_CONVERTED_TO_MODULES);\n\n        // Parse cached descriptor file, if it exists\n        final Optional<PluginsConfig> cachedPluginsConfig = Files.exists(previousConfigPath)\n            ? Optional.of(PluginsConfig.parseConfig(previousConfigPath, CborXContent.cborXContent))\n            : Optional.empty();\n\n        final PluginChanges changes = getPluginChanges(pluginsConfig, cachedPluginsConfig);\n\n        if (changes.isEmpty()) {\n            terminal.println(\"No plugins to install, remove or upgrade\");\n            return;\n        }\n","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/distribution/tools/plugin-cli/src/main/java/org/elasticsearch/plugins/cli/SyncPluginsAction.java#L73-L109","documentation":"Thrown by SyncPluginsAction.execute() when the ES plugins directory (env.pluginsDir()) does not exist on disk. The plugin-sync flow needs this directory to enumerate currently-installed plugins and diff them against elasticsearch-plugins.yml. Its absence means the ES_HOME layout is incomplete or misconfigured.","triggerScenarios":"Calling the sync-plugins command (or booting Docker ES which invokes it) when ES_HOME/plugins is absent — e.g. ES_HOME pointed at a partial/extracted tarball, a custom distribution missing the plugins dir, or the dir was deleted after install.","commonSituations":"Running ES from a manually assembled ES_HOME; containers built from a stripped image; symlinking ES_HOME to a read-only mount that omits plugins/; CI images that prune the plugins directory to save space.","solutions":["Verify ES_HOME is correct: ls $ES_HOME/plugins — the directory should exist alongside lib/, config/, modules/.","If using a custom/tar distribution, re-extract the official archive so the plugins/ directory is recreated.","For Docker, use the official elasticsearch image rather than a hand-built one that drops plugins/.","If the directory was deleted, recreate it empty (mkdir $ES_HOME/plugins) — sync will treat zero installed plugins as a clean slate."],"exampleFix":"# before: ES_HOME=/opt/es-custom (no plugins/ dir)\nls /opt/es-custom/plugins  # -> No such file\n\n# after\nmkdir -p /opt/es-custom/plugins","handlingStrategy":"validation","validationCode":"Path pluginsDir = env.pluginsDir();\nif (Files.exists(pluginsDir) == false) {\n    throw new IllegalStateException(\"Plugins directory missing: \" + pluginsDir\n        + \" — check ES_HOME and re-extract the distribution.\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the official ES distribution archive/Docker image so plugins/ is always present.","In custom images, add a runtime entrypoint check: test -d \"$ES_HOME/plugins\".","Never delete the plugins/ directory even if empty."],"tags":["plugins","docker","sync-plugins","filesystem","config"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}