{"record":{"id":"10b78b49e15157ee","repo":"apache/iceberg","slug":"cannot-initialize-jdbc-table-maintenance-lock-con-10b78b","errorCode":null,"errorMessage":"Cannot initialize JDBC table maintenance lock: Connection failed","messagePattern":"Cannot initialize JDBC table maintenance lock: Connection failed","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"critical","filePath":"flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java","lineNumber":152,"sourceCode":"                    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) {\n      this.pool = pool;\n      this.lockId = lockId;\n      this.type = type;","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java#L134-L170","documentation":"During JdbcLockFactory initialization the SQL operation raised SQLTransientConnectionException or SQLNonTransientConnectionException, meaning the database connection could not be established or failed. It is wrapped as UncheckedSQLException with this message.","triggerScenarios":"JdbcLockFactory.create/open -> initializeLockTables when the driver reports a transient (e.g. pool/connection acquisition) or non-transient connection failure while creating/verifying the lock tables.","commonSituations":"Wrong JDBC host/port, DB restarted or in recovery, connection pool exhausted, firewall/network interruption, or invalid credentials rejected with a connection-class exception.","solutions":["Verify the JDBC URL, host, port and credentials are correct and the database is reachable (test with psql/mysql client).","Check DB server logs and network/firewall rules; restart or failover the DB if it is down.","Retry initialization — transient connection exceptions may clear on their own.","Confirm connection pool sizing isn't exhausting connections shared with other jobs."],"exampleFix":"// before\nlockFactory uri: jdbc:postgresql://wrong-host:5432/app\n// after\nlockFactory uri: jdbc:postgresql://db-primary.internal:5432/app","handlingStrategy":"retry","validationCode":"// preflight connectivity check before creating the lock factory\nConnection c = DriverManager.getConnection(uri, user, pass); // throws SQLException if unreachable\nc.close();","typeGuard":null,"tryCatchPattern":"try {\n  lockFactory.open();\n} catch (UncheckedSQLException e) {\n  if (e.getCause() instanceof SQLTransientConnectionException) {\n    // retry with backoff; transient failures often self-heal\n  } else throw e;\n}","preventionTips":["Validate JDBC URL/credentials with a client before deploying","Ensure network/firewall allows Flink workers to reach the DB","Use a highly available DB endpoint","Watch connection-pool saturation metrics"],"tags":["jdbc","connection-failed","database","lock"],"backgroundTag":"connection-refused","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"}