apache/iceberg · error · UncheckedSQLException

Cannot initialize JDBC table maintenance lock: Query timed…

Error message

Cannot initialize JDBC table maintenance lock: Query timed out

What it means

JdbcLockFactory.initializeLockTables creates the lock table(s) used by the Flink table maintenance trigger lock, running DDL via a connection pool with a query timeout. When the driver throws SQLTimeoutException (statement exceeded its timeout), the factory wraps it in this UncheckedSQLException. The lock infrastructure could not be initialized in time.

Solutions

1. Check the database for blocking sessions/lock contention and kill or wait for them to clear.
2. Increase the JDBC query/connection timeout settings in the lock factory's JDBC URL or pool config.
3. Verify network connectivity and latency between Flink and the database.
4. Retry open() once the database is responsive; check DB server health logs.

Example fix

// before
JdbcLockFactory.forJdbcUrl("jdbc:postgresql://db/app")
// after (allow longer timeout)
JdbcLockFactory.forJdbcUrl("jdbc:postgresql://db/app?connectTimeout=30000&socketTimeout=60000")

// Pre-check DB responsiveness before opening the lock factory
try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass);
     Statement s = c.createStatement()) {
  s.setQueryTimeout(10);
  s.execute("SELECT 1");
}

// catch and retry with backoff
try {
  lockFactory.open();
} catch (UncheckedSQLException e) {
  if (e.getCause() instanceof SQLTimeoutException) {
    Thread.sleep(retryBackoffMs);
    lockFactory.open(); // retry after DB load subsides
  } else { throw e; }
}

When it happens

Trigger: JdbcLockFactory.open() -> initializeLockTables with a database that is slow, locked, or unreachable-with-timeout; lock table creation DDL blocked by another transaction holding metadata locks; very high network latency exceeding the configured query timeout.

Common situations: Database under heavy load or during migrations holding locks on catalog tables; misconfigured low connection/query timeout; network congestion between the Flink JobManager and the JDBC database; DB failing over.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Cannot initialize JDBC table maintenance lock: Query timed…
• Cannot initialize JDBC table maintenance lock
• Cannot initialize JDBC table maintenance lock
• Cannot initialize JDBC table maintenance lock: Connection…
• Cannot initialize JDBC table maintenance lock: Connection…

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

Appendix: source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java:149

                dbMeta.getTables(
                    null /* catalog name */,
                    null /* schemaPattern */,
                    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) {

View on GitHub (pinned to 86d9c8fc54)