apache/iceberg · error · UncheckedSQLException

Cannot update JDBC catalog: Query timed out

Error message

Cannot update JDBC catalog: Query timed out

What it means

Thrown by JdbcCatalog.updateSchemaIfRequired when the schema-migration check/update query times out (SQLTimeoutException). The catalog verifies and optionally upgrades the catalog tables' schema (e.g. V0 to V1 for view support) during initialize(), and this failure means that round trip exceeded the configured JDBC timeout.

Source

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

              } else {
                if (PropertyUtil.propertyAsString(
                        catalogProperties,
                        JdbcUtil.SCHEMA_VERSION_PROPERTY,
                        JdbcUtil.SchemaVersion.V0.name())
                    .equalsIgnoreCase(JdbcUtil.SchemaVersion.V1.name())) {
                  LOG.debug(
                      "{} is being updated to support views", JdbcUtil.CATALOG_TABLE_VIEW_NAME);
                  schemaVersion = JdbcUtil.SchemaVersion.V1;
                  return executeV1CatalogUpdate(conn);
                } else {
                  LOG.warn(VIEW_WARNING_LOG_MESSAGE);
                  return true;
                }
              }
            }
          });
    } catch (SQLTimeoutException e) {
      throw new UncheckedSQLException(e, "Cannot update JDBC catalog: Query timed out");
    } catch (SQLTransientConnectionException | SQLNonTransientConnectionException e) {
      throw new UncheckedSQLException(e, "Cannot update JDBC catalog: Connection failed");
    } catch (SQLException e) {
      throw new UncheckedSQLException(e, "Cannot check and eventually update SQL schema");
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new UncheckedInterruptedException(e, "Interrupted in call to initialize");
    }
  }

  private static boolean executeV1CatalogUpdate(Connection conn) throws SQLException {
    try (PreparedStatement stmt = conn.prepareStatement(JdbcUtil.V1_UPDATE_CATALOG_SQL)) {
      return stmt.execute();
    }
  }

  @Override
  protected TableOperations newTableOps(TableIdentifier tableIdentifier) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Increase the JDBC query timeout (driver URL parameters or pool settings, e.g. socketTimeout/queryTimeout)
2. Check database load and slow-query logs; add indexes on the catalog tables if migration scans are slow
3. Retry initialization once load subsides
4. Upgrade the database/host resources if the catalog table has grown very large

Example fix

// before
props.put("uri", "jdbc:postgresql://db:5432/iceberg"); // default short timeouts
// after
props.put("uri", "jdbc:postgresql://db:5432/iceberg?options=-c%20statement_timeout=300000");

// check configured JDBC timeouts before init
String uri = props.getProperty("uri");
if (uri != null && !uri.contains("timeout")) {
  props.put("uri", uri + "?options=-c%20statement_timeout=300000");
}

try {
  catalog.initialize(name);
} catch (UncheckedSQLException e) {
  if (e.getMessage().contains("timed out")) {
    retryWithBackoff(3); // increase timeout between attempts
  } else { throw e; }
}

When it happens

Trigger: Calling initialize() (via CatalogUtil.loadCatalog) when the database is heavily loaded or the connection's queryTimeout is too small, so the schema check (or V0→V1 migration) statement exceeds the driver's timeout.

Common situations: Large iceberg_catalog tables making migration statements slow, network congestion between app and database, or very low connection pool / driver query timeout settings.

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 check and eventually update SQL schema
• Database Connection timeout
• Cannot initialize JDBC table maintenance lock: Query timed o
• Cannot initialize JDBC catalog: Query timed out
• Cannot initialize JDBC catalog

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