What causes "Failed to extract URI SAN from leaf certificate" in quarkusio/quarkus?

Inspect the cause chain (the wrapped exception) to see the underlying parsing error.

quarkusio/quarkus · error · SpiffeConnectionException

Failed to extract URI SAN from leaf certificate

Error message

Failed to extract URI SAN from leaf certificate

What it means

While reading the leaf certificate's Subject Alternative Names an unexpected exception occurred (e.g. CertificateParsingException), and it is wrapped in this SpiffeConnectionException. This means SAN extraction itself failed, not that the SAN content was invalid.

Source

Thrown at extensions/spiffe-client/runtime/src/main/java/io/quarkus/spiffe/client/runtime/internal/SpiffeValidator.java:187

            List<String> uriSans = new ArrayList<>();
            for (var san : sans) {
                if (san.size() > 1 && san.get(0) instanceof Integer type && type == URI_SAN_TYPE
                        && san.get(1) != null) {
                    uriSans.add(san.get(1).toString());
                }
            }
            if (uriSans.isEmpty()) {
                throw new SpiffeConnectionException("Leaf certificate has no URI Subject Alternative Names");
            }
            if (uriSans.size() > 1) {
                throw new SpiffeConnectionException(
                        "Leaf certificate must contain exactly one URI SAN, found " + uriSans.size() + ": " + uriSans);
            }
            return uriSans.get(0);
        } catch (SpiffeConnectionException e) {
            throw e;
        } catch (Exception e) {
            throw new SpiffeConnectionException("Failed to extract URI SAN from leaf certificate", e);
        }
    }

    private static boolean isValidTrustDomainChar(char c) {
        return (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '.' || c == '-' || c == '_';
    }

    private static boolean isValidPathChar(char c) {
        return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9')
                || c == '.' || c == '-' || c == '_';
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Inspect the cause chain (the wrapped exception) to see the underlying parsing error.
Re-fetch/refresh the trust bundle and certificates — the served certificate may be corrupted or truncated.
Validate the certificate chain offline with openssl x509 -text to pinpoint the malformed extension.

Example fix

// inspect the served cert outside the app
// before: app fails at handshake
// after: openssl s_client -connect host:port | openssl x509 -text -noout | grep -A5 'Alternative'

Defensive patterns

Strategy: try-catch

Validate before calling

boolean isParsable(X509Certificate cert) {
    try { cert.getSubjectAlternativeNames(); return true; }
    catch (Exception e) { return false; }
}

Try / catch

try {
    validator.validateLeaf(chain);
} catch (SpiffeConnectionException e) {
    Throwable cause = e.getCause();
    log.errorf(e, "SAN extraction failed: %s", cause == null ? e.getMessage() : cause.toString());
}

Prevention

Always inspect getCause() to find the underlying parsing error.
Refresh trust bundles / SVIDs if the served certificate appears corrupted.
Validate certificates with openssl when parsing failures recur.

When it happens

Trigger: The generic catch block in extractAndValidateUriSan wraps any non-SpiffeConnectionException thrown by leaf.getSubjectAlternativeNames() or by iterating the SAN collection during validateLeaf.

Common situations: See trigger scenarios.

Understand the failure class

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

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/2d7c952c9b115e60. Report an issue: GitHub.