apache/iceberg · error · UncheckedSQLException

Cannot initialize JDBC catalog

Error message

Cannot initialize JDBC catalog

What it means

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.

Source

Thrown at core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java:226

  private void initializeCatalogTables() {
    LOG.trace("Creating database tables (if missing) to store iceberg catalog");

    try {
      atomicCreateTable(
          JdbcUtil.CATALOG_TABLE_VIEW_NAME,
          JdbcUtil.V0_CREATE_CATALOG_SQL,
          "to store iceberg catalog tables");
      atomicCreateTable(
          JdbcUtil.NAMESPACE_PROPERTIES_TABLE_NAME,
          JdbcUtil.CREATE_NAMESPACE_PROPERTIES_TABLE_SQL,
          "to store iceberg catalog namespace properties");
    } catch (SQLTimeoutException e) {
      throw new UncheckedSQLException(e, "Cannot initialize JDBC catalog: Query timed out");
    } catch (SQLTransientConnectionException | SQLNonTransientConnectionException e) {
      throw new UncheckedSQLException(e, "Cannot initialize JDBC catalog: Connection failed");
    } catch (SQLException e) {
      throw new UncheckedSQLException(e, "Cannot initialize JDBC catalog");
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new UncheckedInterruptedException(e, "Interrupted in call to initialize");
    }
  }

  private void updateSchemaIfRequired() {
    try {
      connections.run(
          conn -> {
            DatabaseMetaData dbMeta = conn.getMetaData();
            try (ResultSet typeColumn =
                dbMeta.getColumns(
                    null, null, JdbcUtil.CATALOG_TABLE_VIEW_NAME, JdbcUtil.RECORD_TYPE)) {
              if (typeColumn.next()) {
                LOG.debug("{} already supports views", JdbcUtil.CATALOG_TABLE_VIEW_NAME);
                schemaVersion = JdbcUtil.SchemaVersion.V1;
                return true;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the JDBC URL targets a supported database (Postgres, MySQL, etc.) and the driver version matches
2. Grant the configured DB user CREATE/SELECT/INSERT privileges on the catalog schema
3. Check for pre-existing partially-created iceberg_catalog/iceberg_namespace_properties tables and repair or drop them
4. Inspect the wrapped SQLException cause for the exact database error and fix accordingly

Example fix

// before
catalogProps.put("uri", "jdbc:mysql://db:3306/iceberg"); // unsupported dialect/version
// after
catalogProps.put("uri", "jdbc:postgresql://db:5432/iceberg");
catalogProps.put("jdbc.user", "iceberg");
catalogProps.put("jdbc.password", "..."); // user has CREATE TABLE on schema "iceberg"

try (Connection c = DriverManager.getConnection(uri, user, pass)) {
  c.createStatement().execute("SELECT 1");
  DatabaseMetaData md = c.getMetaData();
  boolean canCreate = !c.isReadOnly();
}

boolean jdbcReachable(String uri, String user, String pass) {
  try (Connection c = DriverManager.getConnection(uri, user, pass)) {
    return !c.isReadOnly();
  } catch (SQLException e) { return false; }
}

try {
  Catalog catalog = CatalogUtil.loadCatalog("org.apache.iceberg.jdbc.JdbcCatalog", name, impl, props);
} catch (UncheckedSQLException e) {
  LOG.error("JDBC catalog init failed", e.getCause());
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Cannot initialize JDBC catalog: Query timed out
• Cannot initialize JDBC catalog: Connection failed
• Cannot check and eventually update SQL schema
• Failed to execute: %s
• Failed to execute query: %s

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/c1b5858617283b5e. Report an issue: GitHub.