What causes "Setting prefix [{}] must be blank or end in '.'" in elastic/elasticsearch?

Append '.' to the prefix: new SslConfigurationLoader("reindex.ssl.").

elastic/elasticsearch · error · IllegalArgumentException

Setting prefix [{}] must be blank or end in '.'

Error message

Setting prefix [{}] must be blank or end in '.'

What it means

SslConfigurationLoader's constructor requires the setting prefix to be either the empty string or end with a '.', so that expanded keys read naturally (e.g. "reindex.ssl." + "verification_mode"). A non-empty prefix without the trailing dot would silently produce malformed setting keys.

Source

Thrown at libs/ssl-config/src/main/java/org/elasticsearch/common/ssl/SslConfigurationLoader.java:183

    private List<String> defaultCiphers;
    private List<String> defaultProtocols;
    private List<X509Field> defaultRestrictedTrustFields;

    private Function<KeyStore, KeyStore> keyStoreFilter;

    /**
     * Construct a new loader with the "standard" default values.
     *
     * @param settingPrefix The prefix to apply to all settings that are loaded. It may be the empty string, otherwise it
     *                      must end in a "." (period). For example, if the prefix is {@code "reindex.ssl."} then the keys that are
     *                      passed to methods like {@link #getSettingAsString(String)} will be in the form
     *                      {@code "reindex.ssl.verification_mode"}, and those same keys will be reported in error messages (via
     *                      {@link SslConfigException}).
     */
    public SslConfigurationLoader(String settingPrefix) {
        this.settingPrefix = settingPrefix == null ? "" : settingPrefix;
        if (this.settingPrefix.isEmpty() == false && this.settingPrefix.endsWith(".") == false) {
            throw new IllegalArgumentException("Setting prefix [" + settingPrefix + "] must be blank or end in '.'");
        }
        this.defaultTrustConfig = new DefaultJdkTrustConfig();
        this.defaultKeyConfig = EmptyKeyConfig.INSTANCE;
        this.defaultVerificationMode = SslVerificationMode.FULL;
        this.defaultClientAuth = SslClientAuthenticationMode.OPTIONAL;
        this.defaultProtocols = DEFAULT_PROTOCOLS;
        this.defaultCiphers = DEFAULT_CIPHERS;
        this.defaultRestrictedTrustFields = GLOBAL_DEFAULT_RESTRICTED_TRUST_FIELDS;
    }

    /**
     * Change the default trust config.
     * The initial trust config is {@link DefaultJdkTrustConfig}, which trusts the JDK's default CA certs
     */
    public void setDefaultTrustConfig(SslTrustConfig defaultTrustConfig) {
        this.defaultTrustConfig = defaultTrustConfig;
    }

View on GitHub (pinned to db6a809a66)

Solutions

Append '.' to the prefix: new SslConfigurationLoader("reindex.ssl.").
Use the empty string for the top-level/default SSL config.
Centralise prefix constants in one place so they always end in '.'.

Example fix

// before
new SslConfigurationLoader("reindex.ssl");
// after
new SslConfigurationLoader("reindex.ssl.");

Defensive patterns

Strategy: validation

Validate before calling

String normalisePrefix(String p) {
    if (p == null || p.isEmpty()) return "";
    return p.endsWith(".") ? p : p + ".";
}
// then: new SslConfigurationLoader(normalisePrefix(rawPrefix));

Prevention

Keep prefix constants in one place and always include the trailing dot.
Add a unit test that constructs the loader for every prefix constant you define.
Document the rule on the SslConfigurationLoader constructor Javadoc near the constant.

When it happens

Trigger: Instantiating new SslConfigurationLoader("reindex.ssl") or any prefix missing the trailing dot. Common when building a loader programmatically rather than from elasticsearch.yml.

Common situations: Custom plugin code constructing a loader; copy-paste from settings keys that omit the dot; passing a Java constant that was trimmed.

Related errors

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