{"record":{"id":"1894b61a471e263d","repo":"quarkusio/quarkus","slug":"option-localsocket-is-not-available-for-mariadb","errorCode":null,"errorMessage":"Option 'localSocket' is not available for MariaDB in native mode","messagePattern":"Option 'localSocket' is not available for MariaDB in native mode","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/jdbc/jdbc-mariadb/runtime/src/main/java/io/quarkus/jdbc/mariadb/runtime/graal/SimpleSocketHandlerFunction.java","lineNumber":18,"sourceCode":"package io.quarkus.jdbc.mariadb.runtime.graal;\n\nimport java.io.IOException;\nimport java.net.Socket;\nimport java.sql.SQLException;\n\nimport org.mariadb.jdbc.Configuration;\nimport org.mariadb.jdbc.HostAddress;\nimport org.mariadb.jdbc.client.impl.ConnectionHelper;\nimport org.mariadb.jdbc.client.socket.impl.SocketHandlerFunction;\n\npublic class SimpleSocketHandlerFunction implements SocketHandlerFunction {\n    @Override\n    public Socket apply(Configuration conf, HostAddress hostAddress) throws IOException, SQLException {\n        if (conf.pipe() != null) {\n            throw new IllegalArgumentException(getErrorMessage(\"pipe\"));\n        } else if (conf.localSocket() != null) {\n            throw new IllegalArgumentException(getErrorMessage(\"localSocket\"));\n        }\n\n        return ConnectionHelper.standardSocket(conf, hostAddress);\n    }\n\n    private String getErrorMessage(String option) {\n        return \"Option '\" + option + \"' is not available for MariaDB in native mode\";\n    }\n}\n","sourceCodeStart":1,"sourceCodeEnd":28,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/jdbc/jdbc-mariadb/runtime/src/main/java/io/quarkus/jdbc/mariadb/runtime/graal/SimpleSocketHandlerFunction.java#L1-L28","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","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"],"exampleFix":"// before\nString url = \"jdbc:mariadb://localhost/mydb?localSocket=/var/run/mysqld/mysqld.sock\";\n// after\nString url = \"jdbc:mariadb://localhost:3306/mydb\";","handlingStrategy":"validation","validationCode":"if (url.contains(\"localSocket=\")) { throw new IllegalArgumentException(\"MariaDB Unix socket connections are not supported in native mode; use TCP host:port\"); }","typeGuard":"static boolean usesUnixSocket(String url) { return url != null && url.contains(\"localSocket=\"); }","tryCatchPattern":"try { ds.getConnection(); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"localSocket\")) { log.error(\"Switch to TCP connection for native mode\"); } throw e; }","preventionTips":["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"],"tags":["native-image","jdbc","mariadb","unix-socket"],"backgroundTag":"native-image-unsupported-feature","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}