{"record":{"id":"c1b5858617283b5e","repo":"apache/iceberg","slug":"cannot-initialize-jdbc-catalog","errorCode":null,"errorMessage":"Cannot initialize JDBC catalog","messagePattern":"Cannot initialize JDBC catalog","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java","lineNumber":226,"sourceCode":"\n  private void initializeCatalogTables() {\n    LOG.trace(\"Creating database tables (if missing) to store iceberg catalog\");\n\n    try {\n      atomicCreateTable(\n          JdbcUtil.CATALOG_TABLE_VIEW_NAME,\n          JdbcUtil.V0_CREATE_CATALOG_SQL,\n          \"to store iceberg catalog tables\");\n      atomicCreateTable(\n          JdbcUtil.NAMESPACE_PROPERTIES_TABLE_NAME,\n          JdbcUtil.CREATE_NAMESPACE_PROPERTIES_TABLE_SQL,\n          \"to store iceberg catalog namespace properties\");\n    } catch (SQLTimeoutException e) {\n      throw new UncheckedSQLException(e, \"Cannot initialize JDBC catalog: Query timed out\");\n    } catch (SQLTransientConnectionException | SQLNonTransientConnectionException e) {\n      throw new UncheckedSQLException(e, \"Cannot initialize JDBC catalog: Connection failed\");\n    } catch (SQLException e) {\n      throw new UncheckedSQLException(e, \"Cannot initialize JDBC catalog\");\n    } catch (InterruptedException e) {\n      Thread.currentThread().interrupt();\n      throw new UncheckedInterruptedException(e, \"Interrupted in call to initialize\");\n    }\n  }\n\n  private void updateSchemaIfRequired() {\n    try {\n      connections.run(\n          conn -> {\n            DatabaseMetaData dbMeta = conn.getMetaData();\n            try (ResultSet typeColumn =\n                dbMeta.getColumns(\n                    null, null, JdbcUtil.CATALOG_TABLE_VIEW_NAME, JdbcUtil.RECORD_TYPE)) {\n              if (typeColumn.next()) {\n                LOG.debug(\"{} already supports views\", JdbcUtil.CATALOG_TABLE_VIEW_NAME);\n                schemaVersion = JdbcUtil.SchemaVersion.V1;\n                return true;","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java#L208-L244","documentation":"Thrown by JdbcCatalog when creating the backing iceberg_catalog/iceberg_namespace_properties tables fails with a generic SQLException (not a timeout or connection failure, which get specific messages). It means the JDBC catalog could not set up its required metadata tables in the relational database, so the catalog cannot operate.","triggerScenarios":"Calling CatalogUtil.loadCatalog(...\"org.apache.iceberg.jdbc.JdbcCatalog\"...) during initialize() when the underlying database rejects the DDL/queries in initializeCatalogTables — e.g. wrong SQL dialect, insufficient privileges to CREATE TABLE, or a lock conflict on the catalog tables.","commonSituations":"Pointing jdbcCatalog at an unsupported database (dialect mismatch in DDL), a DB user without CREATE TABLE permission, tables locked by another concurrent initializer, or a corrupt/partially-created catalog schema from a previous failed run.","solutions":["Verify the JDBC URL targets a supported database (Postgres, MySQL, etc.) and the driver version matches","Grant the configured DB user CREATE/SELECT/INSERT privileges on the catalog schema","Check for pre-existing partially-created iceberg_catalog/iceberg_namespace_properties tables and repair or drop them","Inspect the wrapped SQLException cause for the exact database error and fix accordingly"],"exampleFix":"// before\ncatalogProps.put(\"uri\", \"jdbc:mysql://db:3306/iceberg\"); // unsupported dialect/version\n// after\ncatalogProps.put(\"uri\", \"jdbc:postgresql://db:5432/iceberg\");\ncatalogProps.put(\"jdbc.user\", \"iceberg\");\ncatalogProps.put(\"jdbc.password\", \"...\"); // user has CREATE TABLE on schema \"iceberg\"","handlingStrategy":"try-catch","validationCode":"try (Connection c = DriverManager.getConnection(uri, user, pass)) {\n  c.createStatement().execute(\"SELECT 1\");\n  DatabaseMetaData md = c.getMetaData();\n  boolean canCreate = !c.isReadOnly();\n}","typeGuard":"boolean jdbcReachable(String uri, String user, String pass) {\n  try (Connection c = DriverManager.getConnection(uri, user, pass)) {\n    return !c.isReadOnly();\n  } catch (SQLException e) { return false; }\n}","tryCatchPattern":"try {\n  Catalog catalog = CatalogUtil.loadCatalog(\"org.apache.iceberg.jdbc.JdbcCatalog\", name, impl, props);\n} catch (UncheckedSQLException e) {\n  LOG.error(\"JDBC catalog init failed\", e.getCause());\n}","preventionTips":["Use a supported database and matching JDBC driver version","Grant the DB user CREATE TABLE privileges on the catalog schema","Test connectivity and DDL rights with a plain JDBC client before wiring up the catalog","Avoid running multiple first-time initializers concurrently against an empty database"],"tags":["jdbc","database","catalog-init","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"}