quarkusio/quarkus · error · ConfigurationException

The SPIFFE client extension does not support unix transport

Error message

The SPIFFE client extension does not support unix transport on Windows, use tcp instead.

What it means

SpiffeDevServicesProcessor starts a local SPIFFE Workload API dev server. When the configured transport resolves to UNIX domain sockets but the build is running on Windows, the processor throws a ConfigurationException because Windows cannot use the unix socket transport — only tcp is supported there.

Source

Thrown at extensions/spiffe-client/deployment/src/main/java/io/quarkus/spiffe/client/deployment/SpiffeDevServicesProcessor.java:85

    void startDevService(SpiffeClientBuildTimeConfig config,
            BuildProducer<DevServicesResultBuildItem> devServicesResultProducer,
            LaunchModeBuildItem launchModeBuildItem) {
        if (ConfigProvider.getConfig().getOptionalValue(ENDPOINT_SOCKET_CONFIG_KEY, String.class).isPresent()) {
            LOG.debug("SPIFFE endpoint socket already configured, skipping SPIFFE Dev Services");
            return;
        }
        if (launchModeBuildItem.getLaunchMode().isRemoteDev()) {
            LOG.warn("SPIFFE Dev Services is not supported in the remote development mode");
            return;
        }
        Transport transport = config.devservices().transport().orElseGet(() -> {
            if (OS.WINDOWS.isCurrent()) {
                return Transport.TCP;
            }
            return Transport.UNIX;
        });
        if (transport == Transport.UNIX && OS.WINDOWS.isCurrent()) {
            throw new ConfigurationException(
                    "The SPIFFE client extension does not support unix transport on Windows, use tcp instead.");
        }
        devServicesResultProducer.produce(
                DevServicesResultBuildItem.<SpiffeWorkloadApiDevServer> owned()
                        .feature(SpiffeClientProcessor.FEATURE)
                        .serviceConfig(config.devservices().hashCode())
                        .startable(() -> new SpiffeWorkloadApiDevServer(transport, config.devservices().httpPort()))
                        .configProvider(Map.of(
                                ENDPOINT_SOCKET_CONFIG_KEY, Startable::getConnectionInfo,
                                BASE_URL_CONFIG_KEY, SpiffeWorkloadApiDevServer::baseUrl))
                        .postStartHook(server -> {
                            if (!server.errorMessages.isEmpty()) {
                                for (String errorMessage : server.errorMessages) {
                                    LOG.error(errorMessage);
                                }
                            } else if (server.endpointSocket != null) {
                                LOG.infof("SPIFFE Workload API server started on %s", server.endpointSocket);
                            }

View on GitHub (pinned to e1c734241f)

Solutions

1. Set the transport to tcp: quarkus.spiffe-client.devservices.transport=tcp in application.properties for Windows.
2. Make the setting OS-conditional (e.g. a Windows profile file application-windows.properties or env var override).
3. Upgrade the extension if a newer version auto-selects tcp on Windows (the processor already maps Windows to Transport.TCP when it controls the choice — explicit config forces unix and hits this error).

Example fix

# before (application.properties, shared)
quarkus.spiffe-client.devservices.transport=unix

# after
quarkus.spiffe-client.devservices.transport=tcp

if (org.apache.commons.lang3.SystemUtils.IS_OS_WINDOWS && "unix".equals(transport)) {
    throw new IllegalStateException("Set quarkus.spiffe-client.devservices.transport=tcp on Windows");
}

When it happens

Trigger: Running Quarkus dev mode / tests with quarkus-spiffe-client dev services on Windows while the transport (quarkus.spiffe-client.devservices.transport or equivalent) resolves to unix; the check `transport == Transport.UNIX && OS.WINDOWS.isCurrent()` fires at dev-service start.

Common situations: A developer copying a Linux/macOS application.properties (with transport=unix or relying on the unix default) onto a Windows machine; CI on Windows runners reusing Linux config; team-shared config not parameterized per-OS.

Related errors

• '%1$scredentials.jwt.source' is set to 'spiffe-jwt', but no
• 'credentials.jwt.source' is set to 'spiffe-jwt', but no SPIF
• Failed to generate EC P-256 signing key
• Failed to create temp socket path
• Failed to start SPIFFE gRPC server on ${transport}

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