quarkusio/quarkus · error · IllegalArgumentException

Option 'pipe' is not available for MariaDB in native mode

Error message

Option 'pipe' is not available for MariaDB in native mode

What it means

MariaDB's native-image socket handler in Quarkus replaces the original SocketHandlerFunction with a Graal substitution that only supports standard TCP sockets. If the JDBC URL requests a named pipe (Windows named pipe connection), the substituted code rejects it at connection time with IllegalArgumentException, because pipe-based transport is not supported by the native build.

Source

Thrown at extensions/jdbc/jdbc-mariadb/runtime/src/main/java/io/quarkus/jdbc/mariadb/runtime/graal/SimpleSocketHandlerFunction.java:16

package io.quarkus.jdbc.mariadb.runtime.graal;

import java.io.IOException;
import java.net.Socket;
import java.sql.SQLException;

import org.mariadb.jdbc.Configuration;
import org.mariadb.jdbc.HostAddress;
import org.mariadb.jdbc.client.impl.ConnectionHelper;
import org.mariadb.jdbc.client.socket.impl.SocketHandlerFunction;

public class SimpleSocketHandlerFunction implements SocketHandlerFunction {
    @Override
    public Socket apply(Configuration conf, HostAddress hostAddress) throws IOException, SQLException {
        if (conf.pipe() != null) {
            throw new IllegalArgumentException(getErrorMessage("pipe"));
        } else if (conf.localSocket() != null) {
            throw new IllegalArgumentException(getErrorMessage("localSocket"));
        }

        return ConnectionHelper.standardSocket(conf, hostAddress);
    }

    private String getErrorMessage(String option) {
        return "Option '" + option + "' is not available for MariaDB in native mode";
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove the 'pipe' parameter from the JDBC URL and connect over TCP (default host/port or explicit host:port)
2. If the MariaDB instance only listens on a named pipe, enable TCP networking on the server (skip-networking=OFF) and connect via localhost:3306
3. Run in JVM mode if a pipe connection is strictly required (native mode will never support it)
4. Use an SSH/socket proxy that exposes the server over TCP

Example fix

// before
String url = "jdbc:mariadb://localhost/mydb?pipe=\\\\.\\pipe\\mysql";
// after
String url = "jdbc:mariadb://localhost:3306/mydb";

if (url.contains("pipe=")) { throw new IllegalArgumentException("MariaDB 'pipe' connections are not supported in native mode; use TCP host:port"); }

static boolean isNativeIncompatibleMariaDbUrl(String url) { return url != null && (url.contains("pipe=") || url.contains("localSocket=")); }

try { ds.getConnection(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("not available for MariaDB in native mode")) { log.error("Rewrite JDBC URL to TCP host:port"); } throw e; }

When it happens

Trigger: Native-mode build/runtime with a MariaDB JDBC URL containing 'pipe' (e.g. jdbc:mariadb://.../?pipe=\\.\pipe\mysql or localSocket combined configuration where conf.pipe() returns non-null) when the socket handler's apply() is invoked while opening a connection.

Common situations: Developers porting a working JVM configuration to native image; Windows setups that previously connected via named pipe to a local MariaDB/MySQL server; copied connection URLs including the pipe parameter.

Related errors

• Option 'localSocket' is not available for MariaDB in native
• Authentication strategy 'dialog' is not supported in GraalVM
• Quarkus does not support Active Directory based authenticati
• Quarkus does not support Keyvault-based column encryption
• Quarkus does not support AAS Enclave

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