apache/iceberg · error · UnsupportedOperationException

Can't convert unknown type

Error message

Can't convert unknown type: ${nested}

What it means

TypeToMessageType converts Iceberg types (nested variants: struct, map, list) into Parquet GroupType/PrimitiveType schemas. When the provided nested Iceberg type is none of struct, map, or list, the converter has no Parquet representation and throws UnsupportedOperationException with the type's string form.

Solutions

1. Inspect the type printed in the message and ensure nested conversion is only invoked for struct/map/list types.
2. Route primitive types through the primitive(...) conversion path instead of the nested branch.
3. Upgrade the iceberg-parquet module so it recognizes the type (custom types require explicit converter support).

Example fix

// before
Type nested = field.type(); // unrecognized type
convertNested(nested);
// after
if (nested.isStructType() || nested.isMapType() || nested.isListType()) {
  convertNested(nested);
} else if (nested.isPrimitiveType()) {
  primitive(nested.asPrimitiveType(), repetition, id, name);
}

void validateNested(Type t) {
  Preconditions.checkArgument(t.isStructType() || t.isMapType() || t.isListType(),
      "Expected nested type (struct/map/list), got: %s", t);
}

boolean isNested(Type t) { return t.isStructType() || t.isMapType() || t.isListType(); }

try {
  parquetSchema = converter.convert(icebergType);
} catch (UnsupportedOperationException e) {
  throw new IllegalArgumentException("Type not convertible to Parquet: " + e.getMessage(), e);
}

When it happens

Trigger: Calling TypeToMessageType.field()/struct()/map()/list() with a nested field whose type is neither a StructType, MapType, nor ListType (i.e. a primitive reaching the nested dispatch path, or an unknown/unrecognized Type implementation).

Common situations: Custom or future Iceberg Type implementations not yet known to the converter; a bug where a primitive type is passed to the nested-type branch; version mismatch where a newer Iceberg type meets an older parquet module.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Cannot convert unknown type to Flink:
• Cannot convert unknown type to Flink
• Cannot convert unsupported type to Spark
• Not a supported type:
• Spark does not support time fields

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

Appendix: source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/TypeToMessageType.java:138

    if (field.type().typeId() == TypeID.UNKNOWN) {
      return null;

    } else if (field.type().isPrimitiveType()) {
      return primitive(field.type().asPrimitiveType(), repetition, id, name);

    } else if (field.type().isVariantType()) {
      return variant(repetition, id, name);

    } else {
      NestedType nested = field.type().asNestedType();
      if (nested.isStructType()) {
        return struct(nested.asStructType(), repetition, id, name);
      } else if (nested.isMapType()) {
        return map(nested.asMapType(), repetition, id, name);
      } else if (nested.isListType()) {
        return list(nested.asListType(), repetition, id, name);
      }
      throw new UnsupportedOperationException("Can't convert unknown type: " + nested);
    }
  }

  public GroupType list(ListType list, Type.Repetition repetition, int id, String name) {
    NestedField elementField = list.fields().get(0);
    Type elementType = field(elementField);
    Preconditions.checkArgument(
        elementType != null, "Cannot convert element Parquet: %s", elementField.type());

    return Types.list(repetition)
        .element(elementType)
        .id(id)
        .named(AvroSchemaUtil.makeCompatibleName(name));
  }

  public GroupType map(MapType map, Type.Repetition repetition, int id, String name) {
    NestedField keyField = map.fields().get(0);
    NestedField valueField = map.fields().get(1);

View on GitHub (pinned to 86d9c8fc54)