{"record":{"id":"b603529ced69d6f7","repo":"quarkusio/quarkus","slug":"spiffe-id-must-have-spiffe-scheme-spiffeid","errorCode":null,"errorMessage":"SPIFFE ID must have 'spiffe://' scheme: ${spiffeId}","messagePattern":"SPIFFE ID must have 'spiffe://' scheme: (.+?)","errorType":"exception","errorClass":"SpiffeConnectionException","httpStatus":null,"severity":"error","filePath":"extensions/spiffe-client/runtime/src/main/java/io/quarkus/spiffe/client/runtime/internal/SpiffeValidator.java","lineNumber":76,"sourceCode":"            String path = uri.getPath();\n            if (path != null && !path.isEmpty() && !\"/\".equals(path)) {\n                throw new SpiffeConnectionException(\n                        \"Signing certificate SPIFFE ID must not have a path component: \" + uriSan);\n            }\n        }\n    }\n\n    static void validateSpiffeId(String spiffeId) throws SpiffeConnectionException {\n        if (spiffeId == null || spiffeId.isEmpty()) {\n            throw new SpiffeConnectionException(\"SPIFFE ID must not be empty\");\n        }\n        if (spiffeId.length() > MAX_SPIFFE_ID_LENGTH) {\n            throw new SpiffeConnectionException(\"SPIFFE ID exceeds maximum length of \" + MAX_SPIFFE_ID_LENGTH\n                    + \" bytes: \" + spiffeId.length());\n        }\n\n        if (!spiffeId.startsWith(SPIFFE_URI_PREFIX)) {\n            throw new SpiffeConnectionException(\"SPIFFE ID must have 'spiffe://' scheme: \" + spiffeId);\n        }\n        if (spiffeId.contains(\"%\")) {\n            throw new SpiffeConnectionException(\"SPIFFE ID must not contain percent-encoded characters: \" + spiffeId);\n        }\n\n        URI uri;\n        try {\n            uri = URI.create(spiffeId);\n        } catch (IllegalArgumentException e) {\n            throw new SpiffeConnectionException(\"SPIFFE ID is not a valid URI: \" + spiffeId, e);\n        }\n\n        if (uri.getUserInfo() != null) {\n            throw new SpiffeConnectionException(\"SPIFFE ID must not contain userinfo: \" + spiffeId);\n        }\n        if (uri.getPort() != -1) {\n            throw new SpiffeConnectionException(\"SPIFFE ID must not contain a port: \" + spiffeId);\n        }","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/spiffe-client/runtime/src/main/java/io/quarkus/spiffe/client/runtime/internal/SpiffeValidator.java#L58-L94","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Prefix the value with spiffe:// and use the form spiffe://<trust-domain>/<path>.","Correct the configuration property to contain the workload's actual SPIFFE ID (check `spire-agent api fetch x509` output).","Add the prefix programmatically only if you are sure the remainder is a valid trust-domain/path."],"exampleFix":"// before\nString id = \"example.org/ns/default/sa/app\";\n// after\nString id = \"spiffe://example.org/ns/default/sa/app\";","handlingStrategy":"validation","validationCode":"if (!spiffeId.startsWith(\"spiffe://\")) {\n    throw new IllegalStateException(\"SPIFFE ID must start with spiffe://: \" + spiffeId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    connection.establish();\n} catch (SpiffeConnectionException e) {\n    if (e.getMessage().contains(\"'spiffe://' scheme\")) {\n        log.error(\"Configured identity is not a SPIFFE URI; fix the config value\", e);\n    }\n    throw e;\n}","preventionTips":["Always copy the exact ID from `spire-agent api fetch x509` output","Distinguish SPIFFE IDs from service URLs in configuration naming","Add a config sanity check at startup"],"tags":["spiffe","validation","uri"],"backgroundTag":"spiffe-id-validation-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}