{"record":{"id":"9245114ab8a48bd3","repo":"apache/iceberg","slug":"cannot-check-and-eventually-update-sql-schema","errorCode":null,"errorMessage":"Cannot check and eventually update SQL schema","messagePattern":"Cannot check and eventually update SQL schema","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java","lineNumber":267,"sourceCode":"                        JdbcUtil.SchemaVersion.V0.name())\n                    .equalsIgnoreCase(JdbcUtil.SchemaVersion.V1.name())) {\n                  LOG.debug(\n                      \"{} is being updated to support views\", JdbcUtil.CATALOG_TABLE_VIEW_NAME);\n                  schemaVersion = JdbcUtil.SchemaVersion.V1;\n                  return executeV1CatalogUpdate(conn);\n                } else {\n                  LOG.warn(VIEW_WARNING_LOG_MESSAGE);\n                  return true;\n                }\n              }\n            }\n          });\n    } catch (SQLTimeoutException e) {\n      throw new UncheckedSQLException(e, \"Cannot update JDBC catalog: Query timed out\");\n    } catch (SQLTransientConnectionException | SQLNonTransientConnectionException e) {\n      throw new UncheckedSQLException(e, \"Cannot update JDBC catalog: Connection failed\");\n    } catch (SQLException e) {\n      throw new UncheckedSQLException(e, \"Cannot check and eventually update SQL schema\");\n    } catch (InterruptedException e) {\n      Thread.currentThread().interrupt();\n      throw new UncheckedInterruptedException(e, \"Interrupted in call to initialize\");\n    }\n  }\n\n  private static boolean executeV1CatalogUpdate(Connection conn) throws SQLException {\n    try (PreparedStatement stmt = conn.prepareStatement(JdbcUtil.V1_UPDATE_CATALOG_SQL)) {\n      return stmt.execute();\n    }\n  }\n\n  @Override\n  protected TableOperations newTableOps(TableIdentifier tableIdentifier) {\n    return new JdbcTableOperations(\n        connections, io, catalogName, tableIdentifier, catalogProperties, schemaVersion);\n  }\n","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java#L249-L285","documentation":"Generic wrap-up thrown by JdbcCatalog.updateSchemaIfRequired for any SQLException that isn't a timeout or connection failure while checking/updating the catalog's SQL schema. The catalog determines the stored schema version and may run a V0→V1 migration; any other database error aborts initialization with this message.","triggerScenarios":"initialize() fails because the schema-check statement errors — e.g. the catalog tables exist with an unexpected structure, the DB user lacks privileges to ALTER TABLE during a V0→V1 migration, or a syntax/feature error from an unsupported database.","commonSituations":"A catalog database created by an older Iceberg version with a foreign/modified schema, a read-only DB account trying to auto-migrate, or manually altered iceberg_catalog tables that no longer match the expected DDL.","solutions":["Inspect the wrapped SQLException cause for the exact database error","Ensure the DB user can ALTER TABLE on the catalog tables (needed for V0→V1 auto-migration)","Set jdbc.schema-version explicitly (V0 or V1) to match the actual database state","Restore the catalog tables to the expected schema (e.g. via the official DDL) if they were manually modified"],"exampleFix":"// before\nprops.put(\"jdbc.schema-version\", \"V1\"); // DB is still V0 and user cannot ALTER\n// after\nprops.put(\"jdbc.schema-version\", \"V0\"); // or grant ALTER on iceberg_catalog, then use V1","handlingStrategy":"try-catch","validationCode":"// ensure DB user can ALTER catalog tables before enabling V1 auto-migration\n// check actual schema state:\n// SELECT * FROM iceberg_catalog LIMIT 1; -- confirm expected columns exist","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(name);\n} catch (UncheckedSQLException e) {\n  throw new RuntimeException(\"JDBC catalog schema check failed; see cause\", e.getCause());\n}","preventionTips":["Do not hand-modify iceberg_catalog/iceberg_namespace_properties tables","Set jdbc.schema-version explicitly to match the actual database state","Grant the DB user ALTER privileges so auto-migration can succeed","Keep catalog DB schema changes in sync with Iceberg upgrades (release notes)"],"tags":["jdbc","database","schema-migration","sql"],"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"}