apache/seatunnel · critical · JdbcConnectorException

CONNECT_DATABASE_FAILED

CONNECT_DATABASE_FAILED

Error message

unable to open JDBC writer

What it means

JdbcOutputFormat.open obtains a connection via connectionProvider.getOrEstablishConnection(); any exception is wrapped in JdbcConnectorException CONNECT_DATABASE_FAILED with message 'unable to open JDBC writer'. This means the sink writer could not reach or authenticate to the database at task start.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/JdbcOutputFormat.java:76

    private transient volatile Exception flushException;
    private transient long lastFlushTimeMs;
    private transient boolean failFastOnRowLevelSqlState;

    public JdbcOutputFormat(
            JdbcConnectionProvider connectionProvider,
            JdbcConnectionConfig jdbcConnectionConfig,
            StatementExecutorFactory<E> statementExecutorFactory) {
        this.connectionProvider = checkNotNull(connectionProvider);
        this.jdbcConnectionConfig = checkNotNull(jdbcConnectionConfig);
        this.statementExecutorFactory = checkNotNull(statementExecutorFactory);
    }

    /** Connects to the target database and initializes the prepared statement. */
    public void open() throws IOException {
        try {
            connectionProvider.getOrEstablishConnection();
        } catch (Exception e) {
            throw new JdbcConnectorException(
                    JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED,
                    "unable to open JDBC writer",
                    e);
        }
        jdbcStatementExecutor = createAndOpenStatementExecutor(statementExecutorFactory);
        lastFlushTimeMs = System.currentTimeMillis();
    }

    private E createAndOpenStatementExecutor(StatementExecutorFactory<E> statementExecutorFactory) {
        E exec = statementExecutorFactory.get();
        try {
            exec.prepareStatements(connectionProvider.getConnection());
        } catch (SQLException e) {
            throw new JdbcConnectorException(
                    CommonErrorCodeDeprecated.SQL_OPERATION_FAILED,
                    "unable to open JDBC writer",
                    e);
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the wrapped cause for the driver-level reason (refused vs auth vs driver-missing)
2. Verify the url, user, password and that the database is reachable from the worker (telnet/nc host port)
3. Place the correct JDBC driver jar in the connector's lib/plugins directory
4. Check max_connections / connection limits and reduce sink parallelism if saturated
5. Confirm SSL/TLS settings and truststore if the DB requires encrypted connections

Example fix

// before
url = "jdbc:mysql://db-prod:3307/mydb" // wrong port; DB listens on 3306
// after
url = "jdbc:mysql://db-prod:3306/mydb"

// pre-flight connectivity check from the worker host
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(host, port), 5000); // throws if unreachable
}
DriverManager.getConnection(url, user, pass).close();

try {
    outputFormat.open();
} catch (JdbcConnectorException e) {
    if (e.getErrorCode() == JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED) {
        retryWithBackoff(() -> outputFormat.open());
    } else {
        throw e;
    }
}

When it happens

Trigger: getOrEstablishConnection fails: host/port wrong or unreachable, wrong user/password, driver class missing, TLS handshake failure, database max connections reached, or URL invalid.

Common situations: Firewall/SG rules blocking the SeaTunnel worker, DB restarted or failover moved the host, expired credentials, forgotten driver jar in the plugin directory, connection pool exhausted by too many writer tasks.

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

• CONNECT_FAILED
• Failed to get connection, interrupted while doing another at
• Get connection failed after retry times
• Failed to discover remaining tables to capture
• Error to check tables:

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