apache/iceberg · error · UncheckedSQLException

Database Connection timeout

Error message

Database Connection timeout

What it means

Thrown when the commit to the JDBC catalog fails with SQLTimeoutException — the database operation (updating the metadata row) timed out, often because a connection could not be obtained within the configured timeout. The commit did not complete, so the table metadata is unchanged.

Source

Thrown at core/src/main/java/org/apache/iceberg/jdbc/JdbcTableOperations.java:123

    String newMetadataLocation = writeNewMetadataIfRequired(newTable, metadata);
    try {
      Map<String, String> table =
          JdbcUtil.loadTable(schemaVersion, connections, catalogName, tableIdentifier);

      if (base != null) {
        validateMetadataLocation(table, base);
        String oldMetadataLocation = base.metadataFileLocation();
        // Start atomic update
        LOG.debug("Committing existing table: {}", tableName());
        updateTable(newMetadataLocation, oldMetadataLocation);
      } else {
        // table not exists create it
        LOG.debug("Committing new table: {}", tableName());
        createTable(newMetadataLocation);
      }

    } catch (SQLTimeoutException e) {
      throw new UncheckedSQLException(e, "Database Connection timeout");
    } catch (SQLTransientConnectionException | SQLNonTransientConnectionException e) {
      throw new UncheckedSQLException(e, "Database Connection failed");
    } catch (DataTruncation e) {
      throw new UncheckedSQLException(e, "Database data truncation error");
    } catch (SQLWarning e) {
      throw new UncheckedSQLException(e, "Database warning");
    } catch (SQLException e) {
      if (JdbcUtil.isConstraintViolation(e)) {
        if (currentMetadataLocation() == null) {
          throw new AlreadyExistsException(e, "Table already exists: %s", tableIdentifier);
        } else {
          throw new UncheckedSQLException(e, "Table already exists: %s", tableIdentifier);
        }
      }

      throw new UncheckedSQLException(e, "Unknown failure");
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Increase JDBC timeout properties in the URL (e.g. connectTimeout, socketTimeout, loginTimeout) or pool timeouts.
2. Check for lock contention on the catalog row from other writers; commit is retried by Iceberg so transient timeouts may succeed on retry.
3. Verify database performance/load at failure time.
4. Retry the commit — Iceberg's commit retry may resolve transient timeouts.

Example fix

// before
String uri = "jdbc:postgresql://db/iceberg?connectTimeout=100";
// after
String uri = "jdbc:postgresql://db/iceberg?connectTimeout=30000&socketTimeout=60000";

// check DB responsiveness and lock waits before committing
long start = System.nanoTime();
try (var conn = java.sql.DriverManager.getConnection(dbUrl, dbProps);
     var st = conn.createStatement(); var rs = st.executeQuery("SELECT 1")) {
  long ms = (System.nanoTime() - start) / 1_000_000;
  if (ms > 5_000) throw new IllegalStateException("Catalog DB slow: " + ms + "ms");
}

try {
  table.refresh();
  table.transaction().commitTransaction();
} catch (UncheckedSQLException e) {
  if (e.getCause() instanceof java.sql.SQLTimeoutException) {
    retryWithBackoff(() -> { /* re-attempt commit */ });
  } else throw e;
}

When it happens

Trigger: doCommit() executes UPDATE/INSERT via the pooled connection and the driver throws SQLTimeoutException (login timeout, socket timeout, or lock wait timeout on the metadata row).

Common situations: Database overloaded or under heavy lock contention on the table row, slow network to DB, very small connection/login timeout configured in JDBC URL properties, long-running transactions blocking the row.

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 update JDBC catalog: Query timed out
• Cannot initialize JDBC table maintenance lock: Query timed o
• Cannot initialize JDBC catalog: Query timed out
• Cannot initialize JDBC catalog
• Cannot update JDBC catalog: Connection failed

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