apache/iceberg · error · java.lang.UnsupportedOperationException

Unsupported StructuredType.

Error message

Unsupported StructuredType.

What it means

FlinkTypeVisitor throws UnsupportedOperationException for StructuredType, Flink's user-defined structured (record-like) type. Iceberg can only represent its own struct types built from named fields, so a Flink StructuredType column cannot be converted by the default visitor.

Solutions

1. Use Flink ROW<...> type instead of a user-defined StructuredType for nested records.
2. Flatten the structured column into scalar columns.
3. Cast the column to ROW<...> before conversion.
4. Subclass FlinkTypeVisitor and override visit(StructuredType) to map fields to Iceberg StructType manually.

Example fix

// before
col 'addr' MyStructuredType  -- user-defined structured type

// after
col 'addr' ROW<street STRING, city STRING>

for (Column col : resolvedSchema.getColumns()) {
  if (col.getDataType().getLogicalType() instanceof StructuredType) {
    throw new IllegalArgumentException("Column '" + col.getName() + "' uses a StructuredType; use ROW<...> instead");
  }
}

try {
  Schema s = FlinkSchemaUtil.toIcebergSchema(flinkSchema);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("StructuredType")) {
    // convert structured columns to ROW types
  } else {
    throw e;
  }
}

When it happens

Trigger: Schema conversion hitting a column whose LogicalType is a StructuredType (user-defined structured type), e.g. columns registered from UDTs or object types, dispatching to visit(StructuredType).

Common situations: Using user-defined structured types or ROW-derived catalog object types in Flink tables stored in Iceberg; connectors that surface UDT columns as StructuredType.

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

• Unsupported DayTimeIntervalType.
• Unsupported DistinctType.
• Unsupported NullType.
• Unsupported RawType.
• Unsupported SymbolType.

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

Appendix: source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/FlinkTypeVisitor.java:58

  @Override
  public T visit(YearMonthIntervalType yearMonthIntervalType) {
    throw new UnsupportedOperationException("Unsupported YearMonthIntervalType.");
  }

  @Override
  public T visit(DayTimeIntervalType dayTimeIntervalType) {
    throw new UnsupportedOperationException("Unsupported DayTimeIntervalType.");
  }

  @Override
  public T visit(DistinctType distinctType) {
    throw new UnsupportedOperationException("Unsupported DistinctType.");
  }

  @Override
  public T visit(StructuredType structuredType) {
    throw new UnsupportedOperationException("Unsupported StructuredType.");
  }

  @Override
  public T visit(NullType nullType) {
    throw new UnsupportedOperationException("Unsupported NullType.");
  }

  @Override
  public T visit(RawType<?> rawType) {
    throw new UnsupportedOperationException("Unsupported RawType.");
  }

  @Override
  public T visit(SymbolType<?> symbolType) {
    throw new UnsupportedOperationException("Unsupported SymbolType.");
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)