quarkusio/quarkus · error · IllegalArgumentException

Option 'localSocket' is not available for MariaDB in native

Error message

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

What it means

Quarkus's Graal substitution for the MariaDB driver's SocketHandlerFunction supports only standard sockets. Unix domain socket connections (localSocket in the JDBC URL) are rejected with IllegalArgumentException because local socket transport is unavailable in native mode.

Source

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

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

Remove 'localSocket' from the JDBC URL and connect over TCP (host:port)
Enable TCP on the MariaDB server and expose the port instead of the socket file
Run the app in JVM mode if Unix socket connectivity is a hard requirement
Use a TCP proxy (e.g. socat) bridging the socket to a local port

Example fix

// before
String url = "jdbc:mariadb://localhost/mydb?localSocket=/var/run/mysqld/mysqld.sock";
// after
String url = "jdbc:mariadb://localhost:3306/mydb";

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try { ds.getConnection(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("localSocket")) { log.error("Switch to TCP connection for native mode"); } throw e; }

Prevention

Prefer TCP over Unix sockets for portable datasource config
Validate JDBC URL keys against native-supported options at startup
Keep socket-based connections only in JVM-mode profiles
Bridge sockets to TCP with socat/proxy if needed

When it happens

Trigger: Native-mode connection to MariaDB with a JDBC URL containing 'localSocket' (e.g. jdbc:mariadb://localhost/mydb?localSocket=/var/run/mysqld/mysqld.sock) — conf.localSocket() returns non-null in the substituted apply().

Common situations: Linux developers connecting to a local MariaDB via its Unix socket file in JVM mode, then building native and hitting this; container images using socket files shared between app and DB containers.

Related errors

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