{"record":{"id":"e89423d7926c0614","repo":"apache/iceberg","slug":"cannot-initialize-jdbc-table-maintenance-lock-que","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":"critical","filePath":"flink/v1.20/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/v1.20/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java#L131-L167","documentation":"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.","triggerScenarios":"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.","commonSituations":"Slow or overloaded MySQL/Postgres instances, long network latency between Flink JobManager and the DB, DB-side lock contention blocking the initialization statements.","solutions":["Check database health and load; resolve blocking transactions or long-running queries holding locks on the maintenance lock tables.","Increase the lock query timeout in the maintenance catalog lock configuration (e.g. lock.query-timeout or JDBC URL socketTimeout).","Verify network connectivity/latency between the Flink cluster and the JDBC endpoint.","Ensure the configured user has CREATE/INSERT privileges so statements don't wait on metadata locks."],"exampleFix":"// before: default timeout too small\n.option(\"lock.query-timeout\", \"1\")\n\n// after\n.option(\"lock.query-timeout\", \"30\")","handlingStrategy":"retry","validationCode":"// preflight: verify DB reachable and responsive before opening the lock factory\ntry (Connection c = DriverManager.getConnection(uri, user, password);\n     Statement s = c.createStatement()) {\n    s.setQueryTimeout(5);\n    s.execute(\"SELECT 1\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    lockFactory.open();\n} catch (UncheckedSQLException e) {\n    if (e.getCause() instanceof SQLTimeoutException) {\n        // retry with backoff after checking DB load/blocking sessions\n        retryOpenWithBackoff();\n    } else {\n        throw e;\n    }\n}","preventionTips":["Set an adequate lock query timeout in configuration","Monitor DB load and blocking sessions on the lock tables","Keep JobManager close (network-wise) to the lock database","Ensure the lock user has all needed privileges so statements don't wait on metadata locks"],"tags":["jdbc","flink","database","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"}