{"record":{"id":"fc5145679bc8d8ed","repo":"apache/iceberg","slug":"cannot-initialize-jdbc-table-maintenance-lock-que-fc5145","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.2/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.2/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java#L131-L167","documentation":"JdbcLockFactory.initializeLockTables creates the maintenance-lock tables via JdbcClientPool within a configured query timeout. If the SQL statement raises SQLTimeoutException (the query timed out), the factory wraps it in UncheckedSQLException with this message. It means the database did not respond in time while setting up lock tables.","triggerScenarios":"JdbcLockFactory.create/open -> initializeLockTables executing CREATE TABLE (or equivalent) for the lock tables when the JDBC driver reports a statement timeout (lock-table DDL blocked by an existing lock or a hung database).","commonSituations":"Slow or overloaded database, DDL waiting on a metadata lock held by another transaction, network latency to a remote DB, or an aggressively small lock.table timeout configured via JdbcLockFactory builder.","solutions":["Check the database for blocking transactions/DDL locks (e.g. pg_locks / information_schema.innodb_trx) and resolve them.","Increase the lock-table acquisition timeout (uriTimeout/timeout in the JdbcLockFactory builder or JDBC URL connect/statement timeout settings).","Verify DB connectivity and health; retry initialization once the database is responsive.","Ensure the lock tables are created up-front (run schema creation manually) so runtime DDL doesn't need to wait."],"exampleFix":"// before\nJdbcLockFactory.createLockFactory(\"jdbc:postgresql://db:5432/app\", \"user\", \"pass\", 5)\n// after\nJdbcLockFactory.createLockFactory(\"jdbc:postgresql://db:5432/app\", \"user\", \"pass\", 60)","handlingStrategy":"retry","validationCode":"// preflight: verify the DB accepts DDL within a few seconds\ntry (Connection c = DriverManager.getConnection(uri, user, pass)) {\n  c.setLoginTimeout(5);\n  c.isValid(5);\n}","typeGuard":null,"tryCatchPattern":"try {\n  TriggerLockFactory f = JdbcLockFactory.createLockFactory(uri, user, pass, timeoutSeconds);\n  f.open();\n} catch (UncheckedSQLException e) {\n  if (e.getCause() instanceof SQLTimeoutException) {\n    // backoff and retry with a larger timeout\n  } else throw e;\n}","preventionTips":["Pre-create the lock tables before starting the job","Size the JDBC timeout generously for slow DBs","Monitor DB for blocking DDL/metadata locks","Test DB connectivity from the Flink cluster network"],"tags":["jdbc","sql-timeout","lock","database"],"backgroundTag":"request-timeout","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}