{"record":{"id":"9be3d6bc157d7d57","repo":"quarkusio/quarkus","slug":"the-spiffe-client-extension-does-not-support-unix-9be3d6","errorCode":null,"errorMessage":"The SPIFFE client extension does not support unix scheme on Windows, use tcp:// instead.","messagePattern":"The SPIFFE client extension does not support unix scheme on Windows, use tcp:// instead\\.","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"extensions/spiffe-client/runtime/src/main/java/io/quarkus/spiffe/client/runtime/internal/SpiffeClientImpl.java","lineNumber":416,"sourceCode":"        @Override\n        public List<String> certificatesPem() {\n            return certsToPem(certificates);\n        }\n\n    }\n\n    private static Exception mapGrpcError(GrpcStatus status, String message) {\n        String detail = message != null ? status.name() + \": \" + message : status.name();\n        if (status == GrpcStatus.PERMISSION_DENIED) {\n            return new SpiffeAuthorizationException(detail);\n        }\n        return new SpiffeConnectionException(detail);\n    }\n\n    private static SocketAddress toSocketAddress(URI uri) {\n        if (\"unix\".equals(uri.getScheme())) {\n            if (OS.WINDOWS.isCurrent()) {\n                throw new ConfigurationException(\n                        \"The SPIFFE client extension does not support unix scheme on Windows, use tcp:// instead.\");\n            }\n            return SocketAddress.domainSocketAddress(uri.getPath());\n        }\n        return SocketAddress.inetSocketAddress(uri.getPort(), uri.getHost());\n    }\n\n    private static void validateAudience(String audience) {\n        if (audience == null) {\n            throw new IllegalArgumentException(\"Audience must not be null\");\n        }\n        if (audience.isBlank()) {\n            throw new IllegalArgumentException(\"Audience must not be blank\");\n        }\n        if (audience.indexOf(' ') >= 0) {\n            throw new IllegalArgumentException(\"Audience must not contain spaces: '\" + audience + \"'\");\n        }\n    }","sourceCodeStart":398,"sourceCodeEnd":434,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/spiffe-client/runtime/src/main/java/io/quarkus/spiffe/client/runtime/internal/SpiffeClientImpl.java#L398-L434","documentation":"The configured SPIRE agent address uses a unix:// scheme, but the application runs on Windows, where the underlying socket implementation cannot create unix-domain socket addresses for this extension. The library refuses the configuration early with a ConfigurationException and suggests using tcp:// instead. This is a deterministic platform/configuration mismatch, not a transient fault.","triggerScenarios":"Setting an address like unix:///tmp/spire-agent-sockets/api.sock (or deriving it from the SPIFFE_ENDPOINT_SOCKET env var) in quarkus.spiffe while running on a Windows host.","commonSituations":"Copying Linux SPIRE configuration to a Windows developer machine or Windows container; CI agents on Windows reusing Linux config; SPIRE agent not available on Windows sockets.","solutions":["Change the address scheme to tcp://127.0.0.1:<port> and configure the SPIRE agent to also listen on TCP.","On Windows development, run the workload in a Linux container/WSL that can reach the unix socket.","Guard configuration per-OS: only use unix scheme on non-Windows hosts.","Do not catch this as retryable — fix the configuration; the error will always recur."],"exampleFix":"// before\nquarkus.spiffe.address=unix:///tmp/spire-agent-sockets/api.sock\n// after\nquarkus.spiffe.address=tcp://127.0.0.1:8001","handlingStrategy":"validation","validationCode":"import io.quarkus.runtime.util.StepTiming; // not required; simple check:\nif (OS.WINDOWS.isCurrent() && address.startsWith(\"unix://\")) {\n    throw new IllegalArgumentException(\"Use tcp:// scheme for the SPIRE agent on Windows\");\n}","typeGuard":"static boolean isWindowsCompatibleAddress(String address) {\n    return !OS.WINDOWS.isCurrent() || !address.startsWith(\"unix://\");\n}","tryCatchPattern":"try {\n    client.connect();\n} catch (ConfigurationException e) {\n    // non-retryable platform mismatch: fail startup with actionable message\n    throw new IllegalStateException(\"SPIRE address scheme unsupported on this OS; use tcp://\", e);\n}","preventionTips":["Use tcp:// scheme whenever Windows is a target platform","Externalize the address via config per environment (dev on Windows vs prod on Linux)","Document the Windows limitation in your project's setup docs","Fail fast in a startup listener by validating the scheme per OS"],"tags":["spiffe","windows","unix-socket","configuration"],"backgroundTag":"unsupported-platform-socket-scheme","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}