quarkusio/quarkus · error · SpiffeConnectionException

SPIFFE ID must have 'spiffe://' scheme: ${spiffeId}

Error message

SPIFFE ID must have 'spiffe://' scheme: ${spiffeId}

What it means

A SPIFFE ID must use the spiffe:// scheme (spiffe://<trust-domain>/<path>). SpiffeValidator.validateSpiffeId throws SpiffeConnectionException when the string does not start with the SPIFFE_URI_PREFIX "spiffe://", rejecting https://, bare hostnames, or similar inputs.

Source

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

            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);
        }

        if (uri.getUserInfo() != null) {
            throw new SpiffeConnectionException("SPIFFE ID must not contain userinfo: " + spiffeId);
        }
        if (uri.getPort() != -1) {
            throw new SpiffeConnectionException("SPIFFE ID must not contain a port: " + spiffeId);
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Prefix the value with spiffe:// and use the form spiffe://<trust-domain>/<path>.
2. Correct the configuration property to contain the workload's actual SPIFFE ID (check `spire-agent api fetch x509` output).
3. Add the prefix programmatically only if you are sure the remainder is a valid trust-domain/path.

Example fix

// before
String id = "example.org/ns/default/sa/app";
// after
String id = "spiffe://example.org/ns/default/sa/app";

if (!spiffeId.startsWith("spiffe://")) {
    throw new IllegalStateException("SPIFFE ID must start with spiffe://: " + spiffeId);
}

try {
    connection.establish();
} catch (SpiffeConnectionException e) {
    if (e.getMessage().contains("'spiffe://' scheme")) {
        log.error("Configured identity is not a SPIFFE URI; fix the config value", e);
    }
    throw e;
}

When it happens

Trigger: Passing an ID like https://example.org/workload, example.org/workload, or a plain DNS name to SPIFFE ID validation — commonly a wrong config value or confusing the SPIFFE ID with the service URL.

Common situations: Configuring quarkus.spiffe.* with the service endpoint instead of the workload identity; hand-editing the trust domain and losing the spiffe:// prefix; copying an X.509 subject CN where a SPIFFE ID is expected.

Related errors

• SPIFFE ID exceeds maximum length of 2048 bytes: ${length}
• SPIFFE ID is not a valid URI: ${spiffeId}
• SPIFFE ID must not contain userinfo: ${spiffeId}
• SPIFFE ID must not contain a port: ${spiffeId}
• SPIFFE ID must not contain a query:

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