quarkusio/quarkus · error · ConfigurationException

The SPIFFE client extension does not support unix scheme on

Error message

The SPIFFE client extension does not support unix scheme on Windows, use tcp:// instead.

What it means

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.

Source

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

        @Override
        public List<String> certificatesPem() {
            return certsToPem(certificates);
        }

    }

    private static Exception mapGrpcError(GrpcStatus status, String message) {
        String detail = message != null ? status.name() + ": " + message : status.name();
        if (status == GrpcStatus.PERMISSION_DENIED) {
            return new SpiffeAuthorizationException(detail);
        }
        return new SpiffeConnectionException(detail);
    }

    private static SocketAddress toSocketAddress(URI uri) {
        if ("unix".equals(uri.getScheme())) {
            if (OS.WINDOWS.isCurrent()) {
                throw new ConfigurationException(
                        "The SPIFFE client extension does not support unix scheme on Windows, use tcp:// instead.");
            }
            return SocketAddress.domainSocketAddress(uri.getPath());
        }
        return SocketAddress.inetSocketAddress(uri.getPort(), uri.getHost());
    }

    private static void validateAudience(String audience) {
        if (audience == null) {
            throw new IllegalArgumentException("Audience must not be null");
        }
        if (audience.isBlank()) {
            throw new IllegalArgumentException("Audience must not be blank");
        }
        if (audience.indexOf(' ') >= 0) {
            throw new IllegalArgumentException("Audience must not contain spaces: '" + audience + "'");
        }
    }

View on GitHub (pinned to e1c734241f)

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.

Example fix

// before
quarkus.spiffe.address=unix:///tmp/spire-agent-sockets/api.sock
// after
quarkus.spiffe.address=tcp://127.0.0.1:8001

Defensive patterns

Strategy: validation

Validate before calling

import io.quarkus.runtime.util.StepTiming; // not required; simple check:
if (OS.WINDOWS.isCurrent() && address.startsWith("unix://")) {
    throw new IllegalArgumentException("Use tcp:// scheme for the SPIRE agent on Windows");
}

Type guard

static boolean isWindowsCompatibleAddress(String address) {
    return !OS.WINDOWS.isCurrent() || !address.startsWith("unix://");
}

Try / catch

try {
    client.connect();
} catch (ConfigurationException e) {
    // non-retryable platform mismatch: fail startup with actionable message
    throw new IllegalStateException("SPIRE address scheme unsupported on this OS; use tcp://", e);
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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