What causes "Interrupted in call to initialize" in apache/iceberg?

Let the application shutdown/cancellation complete — the error is a signal, not a fault in the catalog

apache/iceberg · error · UncheckedInterruptedException

Interrupted in call to initialize

Error message

Interrupted in call to initialize

What it means

Thrown by JdbcCatalog's initializeCatalogTables when the thread is interrupted while creating/initializing the JDBC catalog tables. The interrupt flag is re-set on the thread before throwing, preserving the interruption contract.

Source

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

    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;
              } else {
                if (PropertyUtil.propertyAsString(
                        catalogProperties,

View on GitHub (pinned to 86d9c8fc54)

Solutions

Let the application shutdown/cancellation complete — the error is a signal, not a fault in the catalog
Retry initialization on a non-interrupted thread if interruption was accidental
Avoid interrupting threads that are inside JdbcCatalog.initialize(); check for stray Thread.interrupt() calls
Investigate why the task was cancelled (executor shutdown, future.cancel, watchdog)

Example fix

// before
executor.shutdownNow(); // interrupts thread mid-initialize
// after
executor.shutdown();
executor.awaitTermination(5, TimeUnit.MINUTES); // let initialize() finish first

Defensive patterns

Strategy: try-catch

Validate before calling

if (Thread.currentThread().isInterrupted()) {
  throw new IllegalStateException("thread already interrupted; skipping catalog init");
}

Type guard

boolean canInitialize() { return !Thread.currentThread().isInterrupted(); }

Try / catch

try {
  catalog.initialize(name);
} catch (UncheckedInterruptedException e) {
  Thread.currentThread().interrupt(); // preserve flag, abort startup cleanly
  return;
}

Prevention

Do not interrupt threads that are inside JdbcCatalog.initialize()
Use executor.shutdown() + awaitTermination instead of shutdownNow() during startup
Check for watchdogs/futures.cancel(true) that could interrupt slow init
Retry initialization on a fresh thread if interruption was spurious

When it happens

Trigger: The thread calling CatalogUtil.loadCatalog / JdbcCatalog.initialize() is interrupted (Thread.interrupt()) while blocking in connections.run(...) during catalog table creation — typically from executor shutdown, task cancellation, or a shutdown hook.

Common situations: Cancelling a Spark/Flink job that is initializing the catalog, shutting down an application server during startup, or a timeout framework interrupting slow initialization.

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.

Related errors

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