{"record":{"id":"e2a0ca68afcedbaa","repo":"apache/iceberg","slug":"cannot-initialize-jdbc-table-maintenance-lock","errorCode":null,"errorMessage":"Cannot initialize JDBC table maintenance lock","messagePattern":"Cannot initialize JDBC table maintenance lock","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":155,"sourceCode":"                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;\n    }\n\n    @Override","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java#L137-L173","documentation":"The generic catch-all in JdbcLockFactory.initializeLockTables: any SQLException that is neither a timeout nor a connection-class exception is wrapped in UncheckedSQLException with this unspecific message.","triggerScenarios":"JdbcLockFactory.open() where initialization SQL fails with a plain SQLException — e.g. SQL syntax errors, missing table privileges, unknown database, driver-specific errors.","commonSituations":"Lock-table DDL failures because the configured user lacks CREATE privileges, nonexistent schema/database in the URI, incompatible DB dialect or driver version.","solutions":["Inspect the cause chain (UncheckedSQLException.getCause()) for the real SQL error and error code.","Grant the lock user CREATE/INSERT/SELECT privileges on the lock schema.","Confirm the database/schema in the URI exists and the JDBC driver matches the server version.","Enable driver-level logging to capture the failing statement."],"exampleFix":"// before: user without DDL rights\n.option(\"lock.jdbc.user\", \"readonly_user\")\n\n// after\n.option(\"lock.jdbc.user\", \"iceberg_lock_admin\")","handlingStrategy":"try-catch","validationCode":"// preflight: verify schema and DDL privileges\ntry (Connection c = DriverManager.getConnection(uri, user, password)) {\n    DatabaseMetaData md = c.getMetaData();\n    if (!md.storesLowerCaseIdentifiers() && !md.supportsSchemasInTableDefinitions()) {\n        throw new IllegalStateException(\"Unsupported lock database dialect\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    lockFactory.open();\n} catch (UncheckedSQLException e) {\n    SQLException sql = (SQLException) e.getCause();\n    LOG.error(\"Lock init failed: sqlState={} code={}\", sql.getSQLState(), sql.getErrorCode(), sql);\n    throw e;\n}","preventionTips":["Always inspect the cause chain for the underlying SQL error","Grant CREATE/INSERT/SELECT on the lock schema to the lock user","Verify the database/schema in the URI exists","Match JDBC driver version to the server version"],"tags":["jdbc","flink","database","sql","maintenance-lock"],"backgroundTag":"database-query-failed","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"}