apache/iceberg · error · java.lang.UnsupportedOperationException

JDBC catalog is initialized without view support. To auto-mi

Error message

JDBC catalog is initialized without view support. To auto-migrate the database's schema and enable view support, set jdbc.schema-version=V1

What it means

Thrown by JdbcCatalog.newViewOps when view operations are requested but the catalog's jdbc.schema-version is not V1, meaning the underlying database tables were not migrated to the view-capable schema. This UnsupportedOperationException exists because views require extra catalog tables/columns that a V0 database lacks.

Source

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

    }
  }

  private static boolean executeV1CatalogUpdate(Connection conn) throws SQLException {
    try (PreparedStatement stmt = conn.prepareStatement(JdbcUtil.V1_UPDATE_CATALOG_SQL)) {
      return stmt.execute();
    }
  }

  @Override
  protected TableOperations newTableOps(TableIdentifier tableIdentifier) {
    return new JdbcTableOperations(
        connections, io, catalogName, tableIdentifier, catalogProperties, schemaVersion);
  }

  @Override
  protected ViewOperations newViewOps(TableIdentifier viewIdentifier) {
    if (schemaVersion != JdbcUtil.SchemaVersion.V1) {
      throw new UnsupportedOperationException(VIEW_WARNING_LOG_MESSAGE);
    }
    return new JdbcViewOperations(connections, io, catalogName, viewIdentifier, catalogProperties);
  }

  @Override
  protected String defaultWarehouseLocation(TableIdentifier table) {
    String tableLocation = LocationUtil.tableLocation(table, uniqueTableLocation);
    return SLASH.join(defaultNamespaceLocation(table.namespace()), tableLocation);
  }

  @Override
  public boolean dropTable(TableIdentifier identifier, boolean purge) {
    TableOperations ops = newTableOps(identifier);
    TableMetadata lastMetadata = null;
    if (purge) {
      try {
        lastMetadata = ops.current();
      } catch (NotFoundException e) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

Set jdbc.schema-version=V1 in the catalog properties to enable auto-migration and view support
Restart catalog initialization so updateSchemaIfRequired migrates the database to V1
If you must stay on V0, use tables only and avoid view APIs
Back up the catalog database before the V0→V1 migration

Example fix

// before
props.put("jdbc.schema-version", "V0");
// after
props.put("jdbc.schema-version", "V1"); // enables views; auto-migrates on initialize()

Defensive patterns

Strategy: validation

Validate before calling

JdbcCatalog jdbc = (JdbcCatalog) catalog;
// or check properties before creating views:
String v = catalogProps.getOrDefault("jdbc.schema-version", "");
if (!"V1".equals(v)) {
  throw new IllegalStateException("View support requires jdbc.schema-version=V1");
}

Type guard

boolean viewSupported(Map<String,String> catalogProps) {
  return "V1".equals(catalogProps.getOrDefault("jdbc.schema-version", "V0"));
}

Try / catch

try {
  catalog.loadView(ident);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("view support")) {
    // reconfigure with jdbc.schema-version=V1 and re-init
  } else { throw e; }
}

Prevention

Always set jdbc.schema-version=V1 if you plan to use views
Back up the catalog database before the V0→V1 migration
Gate view code paths on schema version at application startup
Do not pin V0 on deployments that need views

When it happens

Trigger: Any view API call (catalog.loadView, createView, registerView, etc.) on a JdbcCatalog configured with jdbc.schema-version=V0 (or on a legacy V0 database that was not migrated).

Common situations: Upgrading Iceberg and starting to use views while the JDBC catalog database is still on the old V0 schema, or explicitly pinning jdbc.schema-version=V0 for compatibility with older deployments.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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