elastic/elasticsearch · error · PluginSyncException

Plugins config does not exist: {configPath}

Error message

Plugins config does not exist: {configPath}

What it means

Thrown by SyncPluginsAction.execute when env.configDir()/elasticsearch-plugins.yml does not exist. Sync is only ever invoked when the manager believes the file should be there, so its absence is treated as an inconsistent state and surfaces as PluginSyncException (no dedicated exit code — it propagates through the sync flow).

Source

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

                    + pluginsConfig
                    + "] exists, which is used by Elasticsearch on startup to ensure the correct plugins "
                    + "are installed. Instead of using this tool, you need to update this config file and restart Elasticsearch."
            );
        }
    }

    /**
     * Synchronises plugins from the config file to the plugins dir.
     *
     * @throws Exception if anything goes wrong
     */
    public void execute() throws Exception {
        final Path configPath = this.env.configDir().resolve(ELASTICSEARCH_PLUGINS_YML);
        final Path previousConfigPath = this.env.pluginsDir().resolve(ELASTICSEARCH_PLUGINS_YML_CACHE);

        if (Files.exists(configPath) == false) {
            // The `PluginsManager` will have checked that this file exists before invoking the action.
            throw new PluginSyncException("Plugins config does not exist: " + configPath.toAbsolutePath());
        }

        if (Files.exists(env.pluginsDir()) == false) {
            throw new PluginSyncException("Plugins directory missing: " + env.pluginsDir());
        }

        // Parse descriptor file
        final PluginsConfig pluginsConfig = PluginsConfig.parseConfig(configPath, YamlXContent.yamlXContent);
        pluginsConfig.validate(InstallPluginAction.OFFICIAL_PLUGINS, InstallPluginAction.PLUGINS_CONVERTED_TO_MODULES);

        // Parse cached descriptor file, if it exists
        final Optional<PluginsConfig> cachedPluginsConfig = Files.exists(previousConfigPath)
            ? Optional.of(PluginsConfig.parseConfig(previousConfigPath, CborXContent.cborXContent))
            : Optional.empty();

        final PluginChanges changes = getPluginChanges(pluginsConfig, cachedPluginsConfig);

        if (changes.isEmpty()) {

View on GitHub (pinned to db6a809a66)

Solutions

1. Restore elasticsearch-plugins.yml in the configured config dir and rerun the sync / restart the node.
2. Verify config dir correctness (`path.conf` / ES_PATH_CONF) and that the process can read the file.
3. If you did not intend to use sync, ensure the action is not invoked (check PluginsManager trigger conditions).

Example fix

# before: config dir lacks elasticsearch-plugins.yml but sync was triggered
ls <config>/elasticsearch-plugins.yml   # missing
# after: restore the file (or remove the sync trigger)
cp /backup/elasticsearch-plugins.yml <config>/
systemctl restart elasticsearch

// Ensure the yml exists before invoking sync.
Path yml = env.configDir().resolve("elasticsearch-plugins.yml");
if (!Files.exists(yml)) {
    throw new FileNotFoundException("elasticsearch-plugins.yml missing at " + yml);
}

try {
    syncAction.execute();
} catch (PluginSyncException e) {
    if (e.getMessage().contains("does not exist")) {
        // restore the config file or disable the sync trigger
        System.err.println("Config missing; restore elasticsearch-plugins.yml or disable sync.");
    }
    throw e;
}

When it happens

Trigger: execute resolves configPath and previousConfigPath; `Files.exists(configPath) == false` throws PluginSyncException with the absolute path. Normally the PluginsManager checks existence before invoking the action, so hitting this indicates that guard was bypassed or the file was deleted between the check and the call.

Common situations: Race where the yml is removed after the manager's existence check; a custom caller invoking SyncPluginsAction directly without pre-checking; filesystem issue making the file invisible (permissions, broken mount); misconfigured config dir.

Related errors

• 64
• 78
• 78
• classname is a required setting for esplugin
• classname is a forbidden for stable esplugin

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