{"record":{"id":"42a7dec144b70bf4","repo":"apache/iceberg","slug":"cannot-initialize-jdbc-table-maintenance-lock-que-42a7de","errorCode":null,"errorMessage":"Cannot initialize JDBC table maintenance lock: Query timed out","messagePattern":"Cannot initialize JDBC table maintenance lock: Query timed out","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"error","filePath":"flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java","lineNumber":149,"sourceCode":"                dbMeta.getTables(\n                    null /* catalog name */,\n                    null /* schemaPattern */,\n                    LOCK_TABLE_NAME /* tableNamePattern */,\n                    null /* types */)) {\n              if (rs.next()) {\n                LOG.debug(\"Flink maintenance lock table already exists\");\n                return true;\n              }\n            }\n            LOG.info(\"Creating Flink maintenance lock table {}\", LOCK_TABLE_NAME);\n            try (PreparedStatement ps = conn.prepareStatement(CREATE_LOCK_TABLE_SQL)) {\n              ps.execute();\n            }\n\n            return true;\n          });\n    } catch (SQLTimeoutException e) {\n      throw new UncheckedSQLException(\n          e, \"Cannot initialize JDBC table maintenance lock: Query timed out\");\n    } catch (SQLTransientConnectionException | SQLNonTransientConnectionException e) {\n      throw new UncheckedSQLException(\n          e, \"Cannot initialize JDBC table maintenance lock: Connection failed\");\n    } catch (SQLException e) {\n      throw new UncheckedSQLException(e, \"Cannot initialize JDBC table maintenance lock\");\n    } catch (InterruptedException e) {\n      Thread.currentThread().interrupt();\n      throw new UncheckedInterruptedException(e, \"Interrupted in call to initialize\");\n    }\n  }\n\n  private static class JdbcLock implements TriggerLockFactory.Lock {\n    private final JdbcClientPool pool;\n    private final String lockId;\n    private final Type type;\n\n    private JdbcLock(JdbcClientPool pool, String lockId, Type type) {","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java#L131-L167","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the database for blocking sessions/lock contention and kill or wait for them to clear.","Increase the JDBC query/connection timeout settings in the lock factory's JDBC URL or pool config.","Verify network connectivity and latency between Flink and the database.","Retry open() once the database is responsive; check DB server health logs."],"exampleFix":"// before\nJdbcLockFactory.forJdbcUrl(\"jdbc:postgresql://db/app\")\n// after (allow longer timeout)\nJdbcLockFactory.forJdbcUrl(\"jdbc:postgresql://db/app?connectTimeout=30000&socketTimeout=60000\")","handlingStrategy":"retry","validationCode":"// Pre-check DB responsiveness before opening the lock factory\ntry (Connection c = DriverManager.getConnection(jdbcUrl, user, pass);\n     Statement s = c.createStatement()) {\n  s.setQueryTimeout(10);\n  s.execute(\"SELECT 1\");\n}","typeGuard":null,"tryCatchPattern":"// catch and retry with backoff\ntry {\n  lockFactory.open();\n} catch (UncheckedSQLException e) {\n  if (e.getCause() instanceof SQLTimeoutException) {\n    Thread.sleep(retryBackoffMs);\n    lockFactory.open(); // retry after DB load subsides\n  } else { throw e; }\n}","preventionTips":["Set generous connect/socket timeouts in the JDBC URL.","Monitor DB lock contention before maintenance windows.","Keep the lock database on the same network/VPC as the Flink JobManager."],"tags":["jdbc","flink","timeout","maintenance-lock"],"backgroundTag":"request-timeout","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}