apache/iceberg · error · UncheckedSQLException

Cannot initialize JDBC catalog: Connection failed

Error message

Cannot initialize JDBC catalog: Connection failed

What it means

JdbcCatalog.initializeCatalogTables wraps SQLTransientConnectionException and SQLNonTransientConnectionException in UncheckedSQLException with "Cannot initialize JDBC catalog: Connection failed". It means the JDBC driver could not establish or maintain a connection while setting up the catalog's metadata tables.

Source

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

        });
  }

  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);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the JDBC URI (host, port, dbname) and that the database is running and accepting connections.
2. Check network/firewall/security-group rules between the client and the database.
3. Validate username/password and auth/TLS configuration (e.g. sslmode for PostgreSQL).
4. Increase pool size or connection timeout if connections are being exhausted under load.
5. For transient errors, retry initialization after confirming the DB is healthy.

Example fix

// before
"uri" -> "jdbc:postgresql://localhost:5432/iceberg"  // DB on remote host

// after (correct host + TLS)
"uri" -> "jdbc:postgresql://db.prod.internal:5432/iceberg?ssl=true&sslmode=require"

// pre-flight connectivity check
try (Connection c = DriverManager.getConnection(jdbcUri, user, pass)) {
  c.createStatement().executeQuery("SELECT 1");
} catch (SQLException e) {
  throw new IllegalStateException("Cannot reach catalog DB at " + jdbcUri, e);
}

try {
  catalog.initialize("app", props);
} catch (UncheckedSQLException e) {
  if (e.getMessage().contains("Connection failed")) {
    if (isTransient(e.getCause()) && attempt < maxRetries) { backoffAndRetry(); }
    else { throw new ConfigurationException("JDBC catalog unreachable — check uri/credentials/firewall", e); }
  } else { throw e; }
}

When it happens

Trigger: Calling JdbcCatalog.initialize(...) when the driver raises SQLTransientConnectionException or SQLNonTransientConnectionException during CREATE TABLE — wrong host/port, DB down, rejected auth at connection level, or pool exhaustion.

Common situations: Misconfigured jdbc URI (host, port, database name); database container not started or crashed; firewall/security group blocking the DB port; TLS requirement mismatch; wrong credentials; connection pool limit reached.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Cannot initialize JDBC catalog: Query timed out
• Cannot initialize JDBC catalog
• Interrupted in call to initialize
• Cannot update JDBC catalog: Connection failed
• Cannot check and eventually update SQL schema

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