{"record":{"id":"1e740b1a474c5d04","repo":"elastic/elasticsearch","slug":"1-1e740b","errorCode":"1","errorMessage":"plugin directory [%s] already exists; if you need to update the plugin, uninstall it first using command 'remove %s'","messagePattern":"plugin directory \\[(.+?)\\] already exists; if you need to update the plugin, uninstall it first using command 'remove (.+?)'","errorType":"exception","errorClass":"UserException","httpStatus":null,"severity":"error","filePath":"distribution/tools/plugin-cli/src/main/java/org/elasticsearch/plugins/cli/InstallPluginAction.java","lineNumber":830,"sourceCode":"    }\n\n    // checking for existing version of the plugin\n    private static void verifyPluginName(Path pluginPath, String pluginName) throws UserException, IOException {\n        // don't let user install plugin conflicting with module...\n        // they might be unavoidably in maven central and are packaged up the same way)\n        if (MODULES.contains(pluginName)) {\n            throw new UserException(ExitCodes.USAGE, \"plugin '\" + pluginName + \"' cannot be installed as a plugin, it is a system module\");\n        }\n\n        final Path destination = pluginPath.resolve(pluginName);\n        if (Files.exists(destination)) {\n            final String message = String.format(\n                Locale.ROOT,\n                \"plugin directory [%s] already exists; if you need to update the plugin, \" + \"uninstall it first using command 'remove %s'\",\n                destination,\n                pluginName\n            );\n            throw new UserException(PLUGIN_EXISTS, message);\n        }\n    }\n\n    /**\n     * Load information about the plugin, and verify it can be installed with no errors.\n     */\n    private PluginDescriptor loadPluginInfo(Path pluginRoot) throws Exception {\n        final PluginDescriptor info = PluginDescriptor.readFromProperties(pluginRoot);\n        if (info.hasNativeController()) {\n            throw new IllegalStateException(\"plugins can not have native controllers\");\n        }\n        PluginsUtils.verifyCompatibility(info);\n\n        // checking for existing version of the plugin\n        verifyPluginName(env.pluginsDir(), info.getName());\n\n        PluginsUtils.checkForFailedPluginRemovals(env.pluginsDir());\n","sourceCodeStart":812,"sourceCodeEnd":848,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/distribution/tools/plugin-cli/src/main/java/org/elasticsearch/plugins/cli/InstallPluginAction.java#L812-L848","documentation":"Thrown by verifyPluginName (after the module check) when pluginPath.resolve(pluginName) already exists on disk. The install path is occupied, so a fresh install is refused with PLUGIN_EXISTS (1). The message instructs the user to remove the existing plugin first.","triggerScenarios":"Running `install X` when `$ES_HOME/plugins/X` already exists; an earlier failed install left a partial directory; reinstalling without removing.","commonSituations":"Retry-after-failure leaving stub directories; idempotent deployment scripts that re-run install on already-provisioned hosts; manual upgrades done by re-installing.","solutions":["Run `elasticsearch-plugin remove <name>` first, then install.","If the directory is leftover from a failed install, delete it manually: `rm -rf $ES_HOME/plugins/<name>`.","Make deployment scripts idempotent by checking for the directory (or always remove-then-install)."],"exampleFix":"# before\nelasticsearch-plugin install analysis-icu   # dir exists\n# after\nelasticsearch-plugin remove analysis-icu && elasticsearch-plugin install analysis-icu","handlingStrategy":"validation","validationCode":"Path dest = env.pluginsDir().resolve(pluginName);\nif (Files.exists(dest)) {\n    // either skip (already installed) or remove first\n    throw new IllegalStateException(\"Plugin dir exists, run remove first: \" + dest);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Make install scripts idempotent: `remove` (ignore failure) then `install`.","After a failed install, clean up partial plugin directories before retrying."],"tags":["plugin-install","plugin-exists","state-conflict","elasticsearch"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}