{"record":{"id":"1f410c07fbcb9a0f","repo":"apache/seatunnel","slug":"unable-to-connect-to-the-mysql-database-at-hostna","errorCode":null,"errorMessage":"Unable to connect to the MySQL database at <hostname>:<port> with user '<username>': ","messagePattern":"Unable to connect to the MySQL database at <hostname>:<port> with user '<username>': ","errorType":"exception","errorClass":"DebeziumException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/io/debezium/connector/mysql/MySqlStreamingChangeEventSource.java","lineNumber":1245,"sourceCode":"                                        + \" with user '\"\n                                        + connectorConfig.username()\n                                        + \"'\",\n                                e);\n                    }\n                    // Otherwise, we were told to shutdown, so we don't care about the timeout\n                    // exception\n                } catch (AuthenticationException e) {\n                    throw new DebeziumException(\n                            \"Failed to authenticate to the MySQL database at \"\n                                    + connectorConfig.hostname()\n                                    + \":\"\n                                    + connectorConfig.port()\n                                    + \" with user '\"\n                                    + connectorConfig.username()\n                                    + \"'\",\n                            e);\n                } catch (Throwable e) {\n                    throw new DebeziumException(\n                            \"Unable to connect to the MySQL database at \"\n                                    + connectorConfig.hostname()\n                                    + \":\"\n                                    + connectorConfig.port()\n                                    + \" with user '\"\n                                    + connectorConfig.username()\n                                    + \"': \"\n                                    + e.getMessage(),\n                            e);\n                }\n            }\n            while (context.isRunning()) {\n                Thread.sleep(100);\n            }\n        } finally {\n            try {\n                client.disconnect();\n            } catch (Exception e) {","sourceCodeStart":1227,"sourceCodeEnd":1263,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/io/debezium/connector/mysql/MySqlStreamingChangeEventSource.java#L1227-L1263","documentation":"A catch-all handler in MySqlStreamingChangeEventSource: any Throwable other than interruption/timeout/AuthenticationException while connecting to the MySQL binlog stream is wrapped into a DebeziumException 'Unable to connect to the MySQL database at <host>:<port> with user <user>'. It signals the streaming connection could not be established at all.","triggerScenarios":"Any non-auth failure while opening the binlog connection — DNS resolution failure, connection refused, TLS handshake failure, IO errors, or protocol errors thrown by the underlying binlog client connect() call.","commonSituations":"MySQL host/port unreachable or firewalled; server not listening on the configured port; DNS misconfiguration; SSL/TLS mismatch (server requires TLS the client can't negotiate); MySQL restarted or network flake during startup.","solutions":["Test raw connectivity from the SeaTunnel node: mysql -h <host> -P <port> -u <user> -p, or nc -vz <host> <port>.","Check the full wrapped cause 'e' in the logs for the root reason (UnknownHost, ConnectException, SSLHandshakeException, etc.).","Fix DNS/hostname and confirm the correct MySQL port in the source config.","If TLS-related, align the connector's SSL mode/keystore/truststore settings with the server's require_secure_transport policy.","Verify the MySQL account exists and the server allows connections from the job's network (bind-address, skip-networking, firewall/security groups)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-flight connectivity check before starting the CDC source\ntry (Socket s = new Socket()) {\n    s.connect(new InetSocketAddress(host, port), 5000); // fails fast if unreachable\n}\ntry (Connection c = DriverManager.getConnection(\n        \"jdbc:mysql://\" + host + \":\" + port + \"/\", user, pass)) {\n    // reachable and credentials accepted at the JDBC level\n}","typeGuard":null,"tryCatchPattern":"try {\n    startCdcSource(config);\n} catch (DebeziumException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Unable to connect\")) {\n        Throwable root = e.getCause();\n        log.error(\"MySQL binlog connect failed: {}\", root == null ? e : root.getMessage());\n        // transient causes (IO/network) may be retried; DNS/SSL errors need config fixes\n    }\n    throw e;\n}","preventionTips":["Pre-flight test TCP connectivity from every SeaTunnel worker node to the MySQL host:port.","Pin hostnames in DNS or /etc/hosts; avoid reliance on flaky resolution.","Align SSL settings between connector config and server (require_secure_transport, TLS versions).","Ensure firewall/security-group rules allow the job's network to reach MySQL.","Inspect the cause chain in logs to distinguish network vs TLS vs protocol failures."],"tags":["mysql","cdc","network","connection","debezium"],"backgroundTag":"connection-refused","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}