apache/iceberg · critical · UncheckedSQLException

Cannot initialize JDBC table maintenance lock: Query timed o

Error message

Cannot initialize JDBC table maintenance lock: Query timed out

What it means

JdbcLockFactory.initializeLockTables creates the lock-table rows needed for table maintenance trigger locking, executing DDL/DML with a query timeout. When the JDBC driver throws SQLTimeoutException (query exceeded the configured timeout), the SQLException is wrapped in UncheckedSQLException with this message.

Source

Thrown at flink/v1.20/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)

Solutions

1. Check database health and load; resolve blocking transactions or long-running queries holding locks on the maintenance lock tables.
2. Increase the lock query timeout in the maintenance catalog lock configuration (e.g. lock.query-timeout or JDBC URL socketTimeout).
3. Verify network connectivity/latency between the Flink cluster and the JDBC endpoint.
4. Ensure the configured user has CREATE/INSERT privileges so statements don't wait on metadata locks.

Example fix

// before: default timeout too small
.option("lock.query-timeout", "1")

// after
.option("lock.query-timeout", "30")

// preflight: verify DB reachable and responsive before opening the lock factory
try (Connection c = DriverManager.getConnection(uri, user, password);
     Statement s = c.createStatement()) {
    s.setQueryTimeout(5);
    s.execute("SELECT 1");
}

try {
    lockFactory.open();
} catch (UncheckedSQLException e) {
    if (e.getCause() instanceof SQLTimeoutException) {
        // retry with backoff after checking DB load/blocking sessions
        retryOpenWithBackoff();
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling JdbcLockFactory.open() (which invokes initializeLockTables) against a database whose query execution exceeds the lock.query.timeout, e.g. a heavily loaded or network-degraded database while creating/updating lock tables.

Common situations: Slow or overloaded MySQL/Postgres instances, long network latency between Flink JobManager and the DB, DB-side lock contention blocking the initialization statements.

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: Connection fa
• Cannot initialize JDBC table maintenance lock
• Cannot initialize JDBC table maintenance lock: Query timed o
• Cannot update JDBC catalog: Query timed out
• Database Connection timeout

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