{"record":{"id":"8ae26466f56c854b","repo":"apache/iceberg","slug":"cannot-initialize-jdbc-table-maintenance-lock-que-8ae264","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.1/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.1/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java#L131-L167","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify database health and connectivity (ping, simple SELECT 1) from the Flink cluster","Increase the JDBC statement/query timeout configured for the lock factory","Retry the job once the database load subsides; check for lock contention on the maintenance-lock table","Inspect the wrapped SQLTimeoutException cause for the exact statement and tune the database (indexes, DDL locks) accordingly"],"exampleFix":"// before\nJdbcLockFactory.create(jdbcUrl, \"maintenance_lock\", Props) // default tiny timeout, slow DB\n// after\n// increase timeout in the jdbc properties passed to the factory, e.g.\nprops.setProperty(\"lock.query-timeout-sec\", \"60\");\nJdbcLockFactory.create(jdbcUrl, \"maintenance_lock\", props)","handlingStrategy":"try-catch","validationCode":"try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {\n  c.createStatement().executeQuery(\"SELECT 1\"); // cheap reachability probe with same timeouts\n}","typeGuard":null,"tryCatchPattern":"try {\n  lockFactory.open(context);\n} catch (UncheckedSQLException e) {\n  if (e.getCause() instanceof SQLTimeoutException) {\n    // back off and retry with larger timeout / alert DB health\n    throw new JobRecoverableException(\"JDBC lock init timed out; retry or increase query timeout\", e);\n  }\n  throw e;\n}","preventionTips":["Monitor DB latency from the Flink cluster before relying on JDBC locks","Set generous statement/query timeouts for DDL on shared databases","Retry transient timeouts with exponential backoff in the maintenance coordinator"],"tags":["jdbc","network","timeout","flink"],"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"}