apache/iceberg · error · UncheckedSQLException

Database Connection failed

Error message

Database Connection failed

What it means

Thrown by JdbcViewOperations.doCommit when the driver raises SQLTransientConnectionException or SQLNonTransientConnectionException while committing a view — the connection to the catalog database failed. Transient variants may succeed on retry; non-transient ones usually indicate a permanent config or access problem. The commit was not applied.

Source

Thrown at core/src/main/java/org/apache/iceberg/jdbc/JdbcViewOperations.java:117

    try {
      Map<String, String> view =
          JdbcUtil.loadView(JdbcUtil.SchemaVersion.V1, connections, catalogName, viewIdentifier);
      if (base != null) {
        validateMetadataLocation(view, base);
        String oldMetadataLocation = base.metadataFileLocation();
        // Start atomic update
        LOG.debug("Committing existing view: {}", viewName());
        updateView(newMetadataLocation, oldMetadataLocation);
      } else {
        // view does not exist, create it
        LOG.debug("Committing new view: {}", viewName());
        createView(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, "View already exists: %s", viewIdentifier);
        } else {
          throw new UncheckedSQLException(e, "View already exists: %s", viewIdentifier);
        }
      }

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

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Retry the operation — transient connection exceptions often resolve on their own
2. Check DB availability, max_connections, and the JDBC connection pool sizing
3. Validate credentials and network reachability (firewalls, VPC/security groups)
4. Inspect the wrapped SQLException cause to distinguish transient vs non-transient failure

Example fix

// before
view.updateSchema(...); // fails if DB connection drops
// after
Tasks.foreach(() -> view.updateSchema(...))
    .retry(3)
    .exponentialBackoff(100, 1000, 10000)
    .throwFailureWhenFinished();

try (Connection c = DriverManager.getConnection(uri, user, pass)) {
  Preconditions.checkArgument(c.isValid(5), "Cannot connect to catalog DB");
}

try {
  view.refresh();
  view.updateSchema(apply);
} catch (UncheckedSQLException e) {
  if (e.getCause() instanceof SQLTransientConnectionException) {
    retryWithBackoff(); // transient: safe to retry
  } else throw e;
}

When it happens

Trigger: Committing a view create/update when the DB connection is dropped mid-operation, the pool can't obtain a connection, credentials are rejected, or the database is restarting.

Common situations: Database failover/restart during a commit, connection pool exhaustion under concurrent writers, wrong user/password, or max_connections reached on the DB server.

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 update JDBC catalog: Connection failed
• Failed to connect: %s
• Cannot initialize JDBC table maintenance lock: Connection fa
• Cannot initialize JDBC catalog: Connection failed
• Database Connection failed

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