apache/iceberg · critical · UncheckedSQLException

Cannot initialize JDBC table maintenance lock: Connection fa

Error message

Cannot initialize JDBC table maintenance lock: Connection failed

What it means

JdbcLockFactory.initializeLockTables catches SQLTransientConnectionException and SQLNonTransientConnectionException separately from generic timeouts and wraps them as UncheckedSQLException with a 'Connection failed' message, signaling the JDBC connection to the lock database could not be established or was dropped.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java:152

                    LOCK_TABLE_NAME /* tableNamePattern */,
                    null /* types */)) {
              if (rs.next()) {
                LOG.debug("Flink maintenance lock table already exists");
                return true;
              }
            }
            LOG.info("Creating Flink maintenance lock table {}", LOCK_TABLE_NAME);
            try (PreparedStatement ps = conn.prepareStatement(CREATE_LOCK_TABLE_SQL)) {
              ps.execute();
            }

            return true;
          });
    } catch (SQLTimeoutException e) {
      throw new UncheckedSQLException(
          e, "Cannot initialize JDBC table maintenance lock: Query timed out");
    } catch (SQLTransientConnectionException | SQLNonTransientConnectionException e) {
      throw new UncheckedSQLException(
          e, "Cannot initialize JDBC table maintenance lock: Connection failed");
    } catch (SQLException e) {
      throw new UncheckedSQLException(e, "Cannot initialize JDBC table maintenance lock");
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new UncheckedInterruptedException(e, "Interrupted in call to initialize");
    }
  }

  private static class JdbcLock implements TriggerLockFactory.Lock {
    private final JdbcClientPool pool;
    private final String lockId;
    private final Type type;

    private JdbcLock(JdbcClientPool pool, String lockId, Type type) {
      this.pool = pool;
      this.lockId = lockId;
      this.type = type;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the JDBC URI, host, port, and credentials in the maintenance lock configuration.
2. Check DB max_connections and current connection count; raise limits or reduce pool size if exhausted.
3. Test connectivity from the Flink host (e.g. nc/psql) and check firewalls, security groups, TLS settings.
4. If transient, retry the job after the DB recovers; consider increasing connect timeout in the JDBC URL.

Example fix

// before
.option("uri", "jdbc:mysql://db-host:3306/iceberg")

// after: add connect timeout and correct DB
.option("uri", "jdbc:mysql://db-host:3306/iceberg?connectTimeout=10000&socketTimeout=30000")

// preflight connectivity check
try (Connection c = DriverManager.getConnection(uri, user, password)) {
    if (!c.isValid(5)) throw new IllegalStateException("JDBC connection invalid");
}

try {
    lockFactory.open();
} catch (UncheckedSQLException e) {
    Throwable cause = e.getCause();
    if (cause instanceof SQLTransientConnectionException) {
        retryWithBackoff(); // transient: retry is appropriate
    } else {
        throw e; // non-transient: fix config/credentials first
    }
}

When it happens

Trigger: JdbcLockFactory.open() where the driver reports SQLTransientConnectionException (transient connect failure, e.g. too many connections) or SQLNonTransientConnectionException (bad URL, auth refused, connection dropped).

Common situations: Wrong JDBC URL/host/port, DB connection pool exhausted (max_connections reached), firewall or TLS handshake failures, DB restarted mid-initialization.

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

• Cannot initialize JDBC table maintenance lock: Query timed o
• Cannot initialize JDBC table maintenance lock
• Cannot update JDBC catalog: Connection failed
• Failed to connect: %s
• Database Connection failed

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/b695aab205a483ef. Report an issue: GitHub.