What causes "JDBC connection close failed." in apache/seatunnel?

Increase server-side idle timeouts (e.g. MySQL wait_timeout) or reduce checkpoint interval

JDBC connection close failed.

Error message

JDBC connection close failed.

What it means

SimpleJdbcConnectionPoolProviderProxy.closeConnection() removes a pooled connection and calls close(); a SQLException during close is logged as a warning and swallowed. The proxy pool is best-effort cleaned up; the connection object reference is simply discarded.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/connection/SimpleJdbcConnectionPoolProviderProxy.java:72

    @Override
    public boolean isConnectionValid() throws SQLException {
        return poolManager.containsConnection(queueIndex)
                && JdbcConnectionValidationUtils.isConnectionValid(
                        poolManager.getConnection(queueIndex), jdbcConfig);
    }

    @Override
    public Connection getOrEstablishConnection() {
        return poolManager.getConnection(queueIndex);
    }

    @Override
    public void closeConnection() {
        if (poolManager.containsConnection(queueIndex)) {
            try {
                poolManager.remove(queueIndex).close();
            } catch (SQLException e) {
                log.warn("JDBC connection close failed.", e);
            }
        }
    }

    @Override
    public Connection reestablishConnection() {
        closeConnection();
        return getOrEstablishConnection();
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

Increase server-side idle timeouts (e.g. MySQL wait_timeout) or reduce checkpoint interval
Check the warning's cause for driver-specific issues (open transaction, broken socket)
Use connection test/validation query options so stale connections are detected before reuse
Ignore if it occurs during shutdown after a connection failure — cleanup is best-effort

Defensive patterns

Strategy: try-catch

Try / catch

// library swallows the exception; nothing to catch.
// At shutdown, tolerate pooled-connection close warnings:
try { provider.closeConnection(); } catch (RuntimeException ignored) { }

Prevention

Tune server idle timeouts (wait_timeout) longer than checkpoint interval
Use validation queries to prune stale pooled connections
Expect this warning after DB restarts; it is non-fatal cleanup noise

When it happens

Trigger: reestablishConnection() (or explicit closeConnection) finds a pooled connection for the queue index, but Connection.close() throws SQLException — typically because the connection is already dead/broken.

Common situations: DB restart or network failure made the pooled connection stale; driver throws on closing a connection with an unfinished transaction; pool reused across long checkpoint intervals with aggressive server-side timeouts (e.g. wait_timeout).

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/5f4532974a713248. Report an issue: GitHub.