elastic/elasticsearch · error · SslConfigException

cannot retrieve secure setting [{}]

Error message

cannot retrieve secure setting [{}]

What it means

resolveSecureSetting wraps any checked (non-Runtime) Exception thrown by getSecureSetting while reading a secure (keystore-backed) char[] value. RuntimeExceptions are rethrown unchanged. The error names the full setting key (prefix + key) and attaches the cause.

Source

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

            return parser.apply(setting);
        } catch (RuntimeException e) {
            throw e;
        } catch (Exception e) {
            throw new SslConfigException("cannot retrieve setting [" + settingPrefix + key + "]", e);
        }
    }

    private char[] resolveSecureSetting(String key, char[] defaultValue) {
        try {
            char[] setting = getSecureSetting(expandSettingKey(key));
            if (setting == null || setting.length == 0) {
                return defaultValue;
            }
            return setting;
        } catch (RuntimeException e) {
            throw e;
        } catch (Exception e) {
            throw new SslConfigException("cannot retrieve secure setting [" + settingPrefix + key + "]", e);
        }

    }

    private <V> List<V> resolveListSetting(String key, Function<String, V> parser, List<V> defaultValue) {
        try {
            final List<String> list = getSettingAsList(expandSettingKey(key));
            if (list == null || list.isEmpty()) {
                return defaultValue;
            }
            return list.stream().map(parser).collect(Collectors.toList());
        } catch (RuntimeException e) {
            throw e;
        } catch (Exception e) {
            throw new SslConfigException("cannot retrieve setting [" + settingPrefix + key + "]", e);
        }
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Inspect the attached cause — it identifies the real I/O or permission failure.
2. Ensure the keystore file exists, is readable by the ES user, and is well-formed (bin/elasticsearch-keystore list).
3. If using a custom backend, wrap its checked exceptions in RuntimeException inside getSecureSetting.

Example fix

// before: subclass throws checked exception on secure read
public char[] getSecureSetting(String key) throws IOException {
    return secretsManager.readSecret(key);
}
// after: wrap to a RuntimeException
public char[] getSecureSetting(String key) {
    try { return secretsManager.readSecret(key); }
    catch (IOException e) { throw new RuntimeException(e); }
}

try {
    SslConfiguration cfg = loader.load(basePath);
} catch (SslConfigException e) {
    if (e.getMessage().startsWith("cannot retrieve secure setting")) {
        Throwable cause = e.getCause();
        log.error("Secure settings source failure for {}: {}", e.getMessage(), cause.toString());
    }
    throw e;
}

When it happens

Trigger: A custom SslConfigurationLoader subclass's getSecureSetting implementation throws a checked Exception while loading a secure credential (keystore password, key passphrase) — for example a remote secrets backend that throws IOException.

Common situations: Custom secrets-backend integration that throws checked exceptions; corrupted Elasticsearch keystore; permission failure reading the keystore file.

Related errors

• cannot retrieve setting [{}]
• failed to load a KeyManager for certificate/key pair [{}], [
• could not load ssl private key file [{}]
• cannot create trust using PEM certificates [{}]
• Error parsing Private Key [{}], file is empty

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