quarkusio/quarkus · error · UnsupportedOperationException

Unix socket not supported

Error message

Unix socket not supported

What it means

Quarkus's native-mode substitution of ServerAddressHelper.createServerAddress rejects Unix domain socket addresses (.sock) because unix socket channels are deleted in native images (UnixSocketChannelStream is @Delete'd). It throws UnsupportedOperationException when the host ends with '.sock', otherwise builds a normal TCP ServerAddress.

Source

Thrown at extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/graal/MongoClientSubstitutions.java:135

    @Substitute
    private CompressorSubstitute createCompressor(final MongoCompressor mongoCompressor) {
        throw new UnsupportedOperationException("Unsupported compressor in native mode");
    }
}

@TargetClass(UnixSocketChannelStream.class)
@Delete
final class UnixSocketChannelStreamSubstitution {

}

@TargetClass(ServerAddressHelper.class)
final class ServerAddressHelperSubstitution {

    @Substitute
    public static ServerAddress createServerAddress(final String host, final int port) {
        if (host != null && host.endsWith(".sock")) {
            throw new UnsupportedOperationException("Unix socket not supported");
        } else {
            return new ServerAddress(host, port);
        }
    }

}

//TODO: move to a dedicated jna extension that will simply collect JNA substitutions
@TargetClass(com.sun.jna.Native.class)
final class JnaNativeSubstitutions {

    // This method can trick GraalVM into thinking that Classloader#findLibrary is getting called
    @Substitute
    public static String getWebStartLibraryPath(final String libName) {
        return null;
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Connect via TCP instead: use localhost:27017 (drop the .sock host)
2. Expose MongoDB on a TCP port in container/dev environments
3. Use JVM mode if unix socket connectivity is required

Example fix

// before
quarkus.mongodb.connection-string=mongodb://%2Ftmp%2Fmongodb-27017.sock
// after
quarkus.mongodb.connection-string=mongodb://localhost:27017

String host = UriUtils.extractHost(connectionString);
if (host != null && host.endsWith(".sock") && isNativeImage()) {
    throw new IllegalStateException("Unix socket MongoDB addresses are not supported in native mode");
}

try {
    mongoClient = MongoClients.create(connStr);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("Unix socket")) {
        connStr = tcpFallback(connStr); // swap .sock host for localhost:port
    } else throw e;
}

When it happens

Trigger: Configuring a MongoDB connection string like mongodb://%2Ftmp%2Fmongodb-27017.sock or a host ending in .sock while running a native executable.

Common situations: Local MongoDB deployed over a unix socket (common in Linux dev/containers) works in JVM mode, then fails in native mode; quoting a URI copied from a socket-based mongod setup.

Related errors

• Unsupported compressor in native mode
• Option 'localSocket' is not available for MariaDB in native
• Unable to create default SSLContext
• io_uring is not supported with Netty 4.2
• service interface name cannot be null or blank

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