apache/iceberg · error · IllegalStateException

Found unsupported view representations

Error message

Found unsupported view representations: %s

What it means

When creating a view via the REST API, all view version representations must be SQL representations (SQLViewRepresentation); if the request carries a representation of any other type, the handler throws IllegalStateException listing the unsupported representation types, since the server cannot store or interpret them.

Solutions

1. Send only SQL view representations (SqlViewRepresentation with sql and dialect) in the request
2. Upgrade the REST server to a version that supports the representation type being sent
3. Inspect the CreateViewRequest payload and remove/convert unknown representation entries

Example fix

// before
ViewRepresentation rep = new MyCustomRepresentation(...); // non-SQL
// after
SQLViewRepresentation rep = new SQLViewRepresentation("SELECT * FROM t", "spark");

boolean allSql = request.viewVersion().representations().stream()
    .allMatch(r -> r instanceof SQLViewRepresentation);
if (!allSql) throw new IllegalArgumentException("Only SQL view representations are supported");

function isSqlRepresentation(r) { return r instanceof org.apache.iceberg.view.SQLViewRepresentation; }

try {
  resp = CatalogHandlers.createView(catalog, ns, request);
} catch (IllegalStateException e) {
  // inspect e.getMessage() for the unsupported representation types
}

When it happens

Trigger: POST /v1/{prefix}/namespaces/{ns}/views with a CreateViewRequest whose viewVersion.representations() contains a non-SQL representation type (e.g. a representation introduced by a newer spec/extension or a client bug serializing the wrong type).

Common situations: Newer client SDK sending representation types an older server does not know; custom engines emitting non-SQL view representations; corrupted or hand-built CreateViewRequest JSON.

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

• Pre-signing not allowed.
• Service failed
• View does not exist
• AboveMax has no comparator
• Altering a view is not supported by catalog:

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/rest/CatalogHandlers.java:699

    request.validate();

    ViewBuilder viewBuilder =
        catalog
            .buildView(TableIdentifier.of(namespace, request.name()))
            .withSchema(request.schema())
            .withProperties(request.properties())
            .withDefaultNamespace(request.viewVersion().defaultNamespace())
            .withDefaultCatalog(request.viewVersion().defaultCatalog())
            .withLocation(request.location());

    Set<String> unsupportedRepresentations =
        request.viewVersion().representations().stream()
            .filter(r -> !(r instanceof SQLViewRepresentation))
            .map(ViewRepresentation::type)
            .collect(Collectors.toSet());

    if (!unsupportedRepresentations.isEmpty()) {
      throw new IllegalStateException(
          String.format("Found unsupported view representations: %s", unsupportedRepresentations));
    }

    request.viewVersion().representations().stream()
        .filter(SQLViewRepresentation.class::isInstance)
        .map(SQLViewRepresentation.class::cast)
        .forEach(r -> viewBuilder.withQuery(r.dialect(), r.sql()));

    View view = viewBuilder.create();

    return viewResponse(view);
  }

  private static LoadViewResponse viewResponse(View view) {
    ViewMetadata metadata = asBaseView(view).operations().current();
    return ImmutableLoadViewResponse.builder()
        .metadata(metadata)
        .metadataLocation(metadata.metadataFileLocation())

View on GitHub (pinned to 86d9c8fc54)