apache/iceberg · error · 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 maintenance-lock table(s) inside a SQL task with a statement/query timeout. When the database fails to answer within that timeout (SQLTimeoutException), the error is wrapped in UncheckedSQLException with this message, meaning lock-table initialization timed out, not that locking is misconfigured.

Source

Thrown at flink/v2.1/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. Verify database health and connectivity (ping, simple SELECT 1) from the Flink cluster
2. Increase the JDBC statement/query timeout configured for the lock factory
3. Retry the job once the database load subsides; check for lock contention on the maintenance-lock table
4. Inspect the wrapped SQLTimeoutException cause for the exact statement and tune the database (indexes, DDL locks) accordingly

Example fix

// before
JdbcLockFactory.create(jdbcUrl, "maintenance_lock", Props) // default tiny timeout, slow DB
// after
// increase timeout in the jdbc properties passed to the factory, e.g.
props.setProperty("lock.query-timeout-sec", "60");
JdbcLockFactory.create(jdbcUrl, "maintenance_lock", props)

try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {
  c.createStatement().executeQuery("SELECT 1"); // cheap reachability probe with same timeouts
}

try {
  lockFactory.open(context);
} catch (UncheckedSQLException e) {
  if (e.getCause() instanceof SQLTimeoutException) {
    // back off and retry with larger timeout / alert DB health
    throw new JobRecoverableException("JDBC lock init timed out; retry or increase query timeout", e);
  }
  throw e;
}

When it happens

Trigger: Calling JdbcLockFactory.open()/initializeLockTables when the JDBC database is overloaded, the network to the DB is slow, or the configured lock.timeout-* properties are too small for DDL to complete.

Common situations: Shared database under heavy load or during failover; network latency between Flink cluster (e.g. on Kubernetes in another VPC) and the JDBC catalog database; lock DDL contending with long-held locks in the DB.

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 o
• Cannot initialize JDBC table maintenance lock: Connection fa
• Connection to Zookeeper timed out
• Cannot initialize JDBC table maintenance lock: Query timed o
• Connection to Zookeeper timed out

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