apache/iceberg · error · UncheckedSQLException

Cannot initialize JDBC catalog: Query timed out

Error message

Cannot initialize JDBC catalog: Query timed out

What it means

JdbcCatalog.initializeCatalogTables creates the iceberg_tables and iceberg_namespace_properties tables at startup, with a configured login/connection timeout. When a JDBC statement fails with SQLTimeoutException (the query exceeded the driver timeout), the catalog wraps it in UncheckedSQLException with "Cannot initialize JDBC catalog: Query timed out".

Source

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

            throw e;
          }
        });
  }

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

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the database is reachable and not paused; wake/resume the serverless instance.
2. Increase the JDBC timeout settings (e.g. jdbc.loginTimeout / HikariCP connectionTimeout) in the catalog properties.
3. Check the database for lock contention or long-running transactions blocking DDL.
4. Test connectivity with the same JDBC URL/credentials outside the app to isolate network issues.
5. Confirm the schema exists and the user has CREATE privileges so DDL does not stall.

Example fix

// before
Map<String, String> props = Map.of(
  JdbcCatalog.PROPERTY_PREFIX + "user", "iceberg",
  JdbcCatalog.PROPERTY_PREFIX + "password", "pass",
  CatalogProperties.URI, "jdbc:postgresql://db:5432/iceberg");

// after (raise timeout so slow startup succeeds)
Map<String, String> props = Map.of(
  JdbcCatalog.PROPERTY_PREFIX + "user", "iceberg",
  JdbcCatalog.PROPERTY_PREFIX + "password", "pass",
  JdbcCatalog.PROPERTY_PREFIX + "connectionTimeout", "30000",
  CatalogProperties.URI, "jdbc:postgresql://db:5432/iceberg");

// probe the catalog DB before initializing
try (Connection c = DriverManager.getConnection(jdbcUri, user, pass)) {
  c.createStatement().executeQuery("SELECT 1"); // surfaces slow/unreachable DB early
}

try {
  catalog.initialize("app", props);
} catch (UncheckedSQLException e) {
  if (e.getMessage().contains("Query timed out")) {
    // raise connection timeout / wake serverless DB, then retry
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling JdbcCatalog.initialize(...) against a database whose CREATE TABLE (or initial connection) exceeds the configured connection/login timeout, producing SQLTimeoutException during atomicCreateTable.

Common situations: Database under heavy load or long lock contention; network latency to a remote DB; pool connection validation timeouts (e.g. HikariCP connectionTimeout too low); DB paused/slow to wake (serverless databases).

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

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