elastic/elasticsearch · error · SslConfigException

could not resolve ssl client verification mode, unknown valu

Error message

could not resolve ssl client verification mode, unknown value [{}], recognised values are [{}]

What it means

Thrown by SslVerificationMode.parse when resolving an SSL client verification mode string. The parser lowercases the input and looks it up in a fixed map of three keys: none, certificate, full. Any value that does not match one of those three (case-insensitively) raises an SslConfigException listing the allowed values.

Source

Thrown at libs/ssl-config/src/main/java/org/elasticsearch/common/ssl/SslVerificationMode.java:88

     * @return true if certificate verification is enabled
     */
    public abstract boolean isCertificateVerificationEnabled();

    private static final Map<String, SslVerificationMode> LOOKUP = Collections.unmodifiableMap(buildLookup());

    private static Map<String, SslVerificationMode> buildLookup() {
        Map<String, SslVerificationMode> map = new LinkedHashMap<>(3);
        map.put("none", NONE);
        map.put("certificate", CERTIFICATE);
        map.put("full", FULL);
        return map;
    }

    public static SslVerificationMode parse(String value) {
        final SslVerificationMode mode = LOOKUP.get(value.toLowerCase(Locale.ROOT));
        if (mode == null) {
            final String allowedValues = String.join(",", LOOKUP.keySet());
            throw new SslConfigException(
                "could not resolve ssl client verification mode, unknown value ["
                    + value
                    + "], recognised values are ["
                    + allowedValues
                    + "]"
            );
        }
        return mode;
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

Set the verification_mode setting to exactly one of: none, certificate, or full
Check the value in the error's [unknown value] field for typos, stray whitespace, or quotes
If migrating from a config that uses peer or require, map it to full (both hostname and certificate checked)

Example fix

// before
xpack.security.http.ssl.verification_mode: peer
// after
xpack.security.http.ssl.verification_mode: full

Defensive patterns

Strategy: validation

Validate before calling

private static final Set<String> SSL_MODES = Set.of("none", "certificate", "full");
String v = raw == null ? null : raw.trim().toLowerCase(Locale.ROOT);
if (v == null || !SSL_MODES.contains(v)) {
    throw new IllegalArgumentException("Invalid ssl verification_mode: " + raw);
}
SslVerificationMode mode = SslVerificationMode.parse(v);

Type guard

static boolean isSslVerificationMode(String s) {
    if (s == null) return false;
    return Set.of("none", "certificate", "full").contains(s.trim().toLowerCase(Locale.ROOT));
}

Try / catch

try {
    SslVerificationMode mode = SslVerificationMode.parse(value);
} catch (SslConfigException e) {
    // surface to config validation; do not fall back silently
    throw new ConfigException("Invalid setting ssl.verification_mode=" + value, e);
}

Prevention

Keep an allowlist constant next to the config parser
Run config through a validator at load time, not at first SSL handshake
Treat the recognised-values list in the error as authoritative

When it happens

Trigger: Calling SslVerificationMode.parse(value) with a string outside {none, certificate, full}. This is the resolver behind the ssl.verification_mode / xpack.security.transport.ssl.verification_mode settings used when configuring mutual TLS on transport or http.

Common situations: A typo in elasticsearch.yml (e.g. verification_mode: ful, peer, true, off, optional); migrating from another product's vocabulary that uses peer/require/request; copy-pasting a setting that another SSL library accepts but this lookup does not.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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