Troubleshoot Apache Iceberg views

When you create, query, alter, or delete Apache Iceberg views in the Lakehouse runtime catalog, you might encounter errors such as name conflicts with tables, access denials, time travel on a view, expired snapshots, unsupported catalog types, or an immutable view location. This document helps you identify the cause of these common errors and resolve them. For general catalog issues, see Troubleshooting.

409 Conflict or AlreadyExistsException when creating or replacing a view or table

Tables and views share the same identifier namespace within a catalog namespace, and the catalog blocks cross-type overwrites. You can't create a view with the same name as an existing table, or a table with the same name as an existing view.

To find the name collision, list both tables and views in the namespace:

SHOW TABLES IN NAMESPACE_NAME;
SHOW VIEWS IN NAMESPACE_NAME;

Choose a different name, or drop the conflicting object first.

403 Forbidden or AccessDeniedException on view operations

Because your compute engine evaluates views client-side, querying a view requires permissions on the view and on every table that the view references. Verify the following:

  • For view DDL, the caller has BigLake Editor (roles/biglake.editor) or BigLake Admin (roles/biglake.admin).
  • For SELECT queries, the caller has BigLake Viewer (roles/biglake.viewer), which grants biglake.views.get on the view and biglake.tables.get and biglake.tables.getData on the referenced tables.
  • In end-user credentials mode, the caller has Storage Object User (roles/storage.objectUser) on the Cloud Storage bucket for view DDL, or Storage Object Viewer (roles/storage.objectViewer) for read-only queries.
  • In credential vending mode, the catalog's service account has Storage Object User (roles/storage.objectUser) on the Cloud Storage bucket, and Spark is configured with spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials.

For more information, see Required roles and permissions.

UNSUPPORTED_FEATURE.TIME_TRAVEL_ON_VIEW

Spark returns AnalysisException: [UNSUPPORTED_FEATURE.TIME_TRAVEL_ON_VIEW] Cannot time travel on view when a query applies TIMESTAMP AS OF or VERSION AS OF directly to a view identifier.

Remove the time travel clause from the query. If you need historical data, define a view whose SQL definition applies TIMESTAMP AS OF to the underlying table, or use a CTE that queries the underlying table directly. For more information, see Create a view with time travel on underlying tables.

ValidationException: Cannot find snapshot older than timestamp

A view defined with a time travel clause references a snapshot that has expired or been removed from the underlying table.

Replace the view with CREATE OR REPLACE VIEW using a newer timestamp or snapshot ID, or adjust the snapshot retention settings on the underlying Iceberg table.

409 Conflict: Namespace is not empty when dropping a namespace

You can't drop a namespace that still contains views. List and drop any remaining views, and then drop the namespace:

SHOW VIEWS IN NAMESPACE_NAME;
DROP VIEW IF EXISTS NAMESPACE_NAME.VIEW_NAME;

400 Bad Request with FAILED_PRECONDITION on view operations

Iceberg views are supported only in multiple-bucket catalogs and single-bucket catalogs. The catalog rejects view operations on BigQuery catalogs or federated catalogs. Create the view in a supported catalog type.

400 Bad Request: View location is immutable

You can't change a view's storage location after you create the view. Remove the location update from your request.

In Trino 481 and earlier, CREATE OR REPLACE VIEW sends a location update that triggers this error. Upgrade to Trino 482 or later, or run DROP VIEW followed by CREATE VIEW to update the view definition. For more information, see Trino support.

What's next