apache/iceberg · error · UncheckedSQLException

Cannot initialize JDBC table maintenance lock: Connection fa

Error message

Cannot initialize JDBC table maintenance lock: Connection failed

What it means

JdbcLockFactory.initializeLockTables also translates SQLTransientConnectionException and SQLNonTransientConnectionException into UncheckedSQLException with the message 'Cannot initialize JDBC table maintenance lock: Connection failed'. It means the JDBC driver could not establish or maintain a connection while creating the lock tables.

Source

Thrown at flink/v2.1/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. Check the wrapped SQLException cause for the underlying reason (unknown host, refused, auth)
2. Verify JDBC URL, credentials, and network reachability from all Flink TaskManagers
3. Confirm the database is running and has free connection slots (max_connections)
4. Retry after transient network issues; the source exception is a transient-connection class, so a job restart often succeeds

Example fix

// before
JdbcLockFactory.create("jdbc:postgresql://db-wrong-host:5432/iceberg", "lock_tbl", props);
// after
JdbcLockFactory.create("jdbc:postgresql://db-correct-host:5432/iceberg", "lock_tbl", props);

try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {
  if (!c.isValid(5)) throw new IllegalStateException("JDBC connection not valid before opening lock factory");
}

try {
  lockFactory.open(context);
} catch (UncheckedSQLException e) {
  Throwable cause = e.getCause();
  if (cause instanceof SQLTransientConnectionException) {
    // transient: retry with backoff
    return Retries.retryWithBackoff(() -> reopen(context), 3);
  }
  throw e; // non-transient: fail fast, likely config/network misconfiguration
}

When it happens

Trigger: JdbcLockFactory.open() when the database is unreachable, credentials/network are broken, max connections are exhausted, or the DB rejects transiently (connection pool saturated).

Common situations: Wrong JDBC host/port or security-group/firewall blocking the Flink workers; database restarted or in failover; connection pool exhausted by other jobs; TLS/credential misconfiguration.

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 update JDBC catalog: Connection failed
• Failed to connect: %s
• Database Connection failed
• Cannot initialize JDBC table maintenance lock: Connection fa
• Cannot initialize JDBC table maintenance lock: Query timed o

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