apache/iceberg · error · UncheckedSQLException

Failed to get view from catalog

Error message

Failed to get view %s from catalog %s

What it means

Thrown by JdbcViewOperations.doRefresh when loading the view row from the JDBC catalog throws a SQLException. The raw SQL error is wrapped in UncheckedSQLException with the view identifier and catalog name for context. It indicates a database-level failure while reading view metadata — connectivity, SQL syntax/schema issues, or permissions.

Solutions

1. Verify database connectivity and credentials in the catalog's URI/user properties
2. Confirm the JDBC catalog schema is initialized (iceberg_views table exists with expected columns)
3. Check DB user permissions for SELECT on catalog tables
4. Inspect the wrapped SQLException cause for the precise driver error

Example fix

// before
View view = catalog.loadView(ident); // fails with UncheckedSQLException
// after
// check catalog config first
Map<String, String> props = Map.of(
  CatalogProperties.URI, "jdbc:postgresql://host:5432/db",
  JdbcCatalog.PROPERTY_PREFIX + "user", "iceberg",
  JdbcCatalog.PROPERTY_PREFIX + "password", "...");
View view = new JdbcCatalog(...).loadView(ident);

// Validate catalog config before use
Preconditions.checkNotNull(props.get(CatalogProperties.URI), "JDBC URI required");
Preconditions.checkNotNull(props.get(JdbcCatalog.PROPERTY_PREFIX + "user"), "JDBC user required");
Preconditions.checkNotNull(props.get(JdbcCatalog.PROPERTY_PREFIX + "password"), "JDBC password required");

try {
  View view = catalog.loadView(ident);
} catch (UncheckedSQLException e) {
  // inspect e.getCause() (SQLException) for SQLState/retryability
  if (isTransient(e)) retryWithBackoff(); else throw e;
}

When it happens

Trigger: Calling catalog.loadView / doRefresh when the database is unreachable, the connection pool is exhausted, the iceberg_views table is missing or has an unexpected schema, or the DB user lacks SELECT privileges.

Common situations: Misconfigured JDBC URL/credentials, database restarted or network partition, catalog tables not initialized (missing schema), or upgrading Iceberg against an older/partially-migrated JDBC catalog.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Cannot check and eventually update SQL schema
• Cannot initialize JDBC catalog
• Cannot initialize JDBC catalog: Connection failed
• Cannot initialize JDBC catalog: Query timed out
• Cannot initialize JDBC table maintenance lock

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

Appendix: source

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

    this.catalogName = catalogName;
    this.viewIdentifier = viewIdentifier;
    this.fileIO = fileIO;
    this.connections = dbConnPool;
    this.catalogProperties = catalogProperties;
  }

  @Override
  protected void doRefresh() {
    Map<String, String> view;

    try {
      view = JdbcUtil.loadView(JdbcUtil.SchemaVersion.V1, connections, catalogName, viewIdentifier);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new UncheckedInterruptedException(e, "Interrupted during refresh");
    } catch (SQLException e) {
      // SQL exception happened when getting view from catalog
      throw new UncheckedSQLException(
          e, "Failed to get view %s from catalog %s", viewIdentifier, catalogName);
    }

    if (view.isEmpty()) {
      if (currentMetadataLocation() != null) {
        throw new NoSuchViewException("View does not exist: %s", viewIdentifier);
      } else {
        this.disableRefresh();
        return;
      }
    }

    String newMetadataLocation = view.get(JdbcTableOperations.METADATA_LOCATION_PROP);
    Preconditions.checkState(
        newMetadataLocation != null, "Invalid view %s: metadata location is null", viewIdentifier);
    refreshFromMetadataLocation(newMetadataLocation);
  }

View on GitHub (pinned to 86d9c8fc54)