What causes "Unable to connect to the MySQL database at : with user ' ': " in apache/seatunnel?

Test raw connectivity from the SeaTunnel node: mysql -h -P -u -p, or nc -vz .

apache/seatunnel · error · DebeziumException

Unable to connect to the MySQL database at <hostname>:<port>

Error message

Unable to connect to the MySQL database at <hostname>:<port> with user '<username>':

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/io/debezium/connector/mysql/MySqlStreamingChangeEventSource.java:1245

                                        + " with user '"
                                        + connectorConfig.username()
                                        + "'",
                                e);
                    }
                    // Otherwise, we were told to shutdown, so we don't care about the timeout
                    // exception
                } catch (AuthenticationException e) {
                    throw new DebeziumException(
                            "Failed to authenticate to the MySQL database at "
                                    + connectorConfig.hostname()
                                    + ":"
                                    + connectorConfig.port()
                                    + " with user '"
                                    + connectorConfig.username()
                                    + "'",
                            e);
                } catch (Throwable e) {
                    throw new DebeziumException(
                            "Unable to connect to the MySQL database at "
                                    + connectorConfig.hostname()
                                    + ":"
                                    + connectorConfig.port()
                                    + " with user '"
                                    + connectorConfig.username()
                                    + "': "
                                    + e.getMessage(),
                            e);
                }
            }
            while (context.isRunning()) {
                Thread.sleep(100);
            }
        } finally {
            try {
                client.disconnect();
            } catch (Exception e) {

View on GitHub (pinned to cf67b549a7)

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).

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight connectivity check before starting the CDC source
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(host, port), 5000); // fails fast if unreachable
}
try (Connection c = DriverManager.getConnection(
        "jdbc:mysql://" + host + ":" + port + "/", user, pass)) {
    // reachable and credentials accepted at the JDBC level
}

Try / catch

try {
    startCdcSource(config);
} catch (DebeziumException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unable to connect")) {
        Throwable root = e.getCause();
        log.error("MySQL binlog connect failed: {}", root == null ? e : root.getMessage());
        // transient causes (IO/network) may be retried; DNS/SSL errors need config fixes
    }
    throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/1f410c07fbcb9a0f. Report an issue: GitHub.