quarkusio/quarkus · error · SpiffeConnectionException

SPIFFE ID must not be empty

Error message

SPIFFE ID must not be empty

What it means

SpiffeValidator.validateSpiffeId requires a non-null, non-empty SPIFFE ID string; an empty (or null) ID is not a valid SPIFFE URI and is rejected with SpiffeConnectionException before any other checks.

Source

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

        if (keyUsage == null || keyUsage.length <= 5 || !keyUsage[5]) {
            throw new SpiffeConnectionException(
                    "Signing certificate must have 'keyCertSign' as key usage: " + cert.getSubjectX500Principal());
        }
        // X.509-SVID 3.2 MUST: if signing cert has a SPIFFE ID, it must not have a path component
        String uriSan = extractOptionalUriSan(cert);
        if (uriSan != null && uriSan.startsWith(SPIFFE_URI_PREFIX)) {
            URI uri = URI.create(uriSan);
            String path = uri.getPath();
            if (path != null && !path.isEmpty() && !"/".equals(path)) {
                throw new SpiffeConnectionException(
                        "Signing certificate SPIFFE ID must not have a path component: " + uriSan);
            }
        }
    }

    static void validateSpiffeId(String spiffeId) throws SpiffeConnectionException {
        if (spiffeId == null || spiffeId.isEmpty()) {
            throw new SpiffeConnectionException("SPIFFE ID must not be empty");
        }
        if (spiffeId.length() > MAX_SPIFFE_ID_LENGTH) {
            throw new SpiffeConnectionException("SPIFFE ID exceeds maximum length of " + MAX_SPIFFE_ID_LENGTH
                    + " bytes: " + spiffeId.length());
        }

        if (!spiffeId.startsWith(SPIFFE_URI_PREFIX)) {
            throw new SpiffeConnectionException("SPIFFE ID must have 'spiffe://' scheme: " + spiffeId);
        }
        if (spiffeId.contains("%")) {
            throw new SpiffeConnectionException("SPIFFE ID must not contain percent-encoded characters: " + spiffeId);
        }

        URI uri;
        try {
            uri = URI.create(spiffeId);
        } catch (IllegalArgumentException e) {
            throw new SpiffeConnectionException("SPIFFE ID is not a valid URI: " + spiffeId, e);

View on GitHub (pinned to e1c734241f)

Solutions

  1. Set the SPIFFE ID / workload identity in your configuration (e.g. quarkus.spiffe.<...>.spiffe-id) to a full spiffe://trust-domain/path value.
  2. Ensure the SPIFFE workload agent is running and returns a valid SVID for the workload.
  3. Add a startup check that fails fast with a clear message when the ID is missing.

Example fix

// before
# application.properties
quarkus.spiffe.cert-source.spiffe-id=
// after
quarkus.spiffe.cert-source.spiffe-id=spiffe://example.org/ns/default/sa/my-service
Defensive patterns

Strategy: validation

Validate before calling

if (spiffeId == null || spiffeId.isEmpty()) {
    throw new IllegalStateException("SPIFFE ID must be configured (spiffe://trust-domain/path)");
}

Try / catch

try {
    connection.establish();
} catch (SpiffeConnectionException e) {
    if (e.getMessage().contains("must not be empty")) {
        log.error("No SPIFFE ID configured; check quarkus.spiffe.* properties and workload agent", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Passing null or "" to SPIFFE ID validation — typically an unset workload identity configuration property, an empty env var, or a workload API response missing the ID field.

Common situations: quarkus.spiffe.* config key left empty in application.properties; SPIFFE_WORKLOAD_API socket configured but agent returned an empty identity; startup code reading an env variable that is not set.

Related errors

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