apache/beam · error · RuntimeException

Unrecognized Iceberg Type: {typeId}

Error message

Unrecognized Iceberg Type: {typeId}

What it means

IcebergUtils.icebergTypeToBeamFieldType converts an Iceberg type's typeId to a Beam Schema.FieldType. Any typeId that falls through the supported switch cases (struct, list, map handled explicitly; primitives above) hits the default branch and throws RuntimeException. It indicates a primitive or exotic Iceberg type the converter does not handle.

Source

Thrown at sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/IcebergUtils.java:139

      case UUID:
      case BINARY:
      case FIXED:
        return Schema.FieldType.BYTES;
      case DECIMAL:
        return Schema.FieldType.DECIMAL;
      case STRUCT:
        return Schema.FieldType.row(
            icebergStructTypeToBeamSchema(type.asStructType(), updateCompatibilityVersion));
      case LIST:
        return Schema.FieldType.array(
            icebergTypeToBeamFieldType(
                type.asListType().elementType(), updateCompatibilityVersion));
      case MAP:
        return Schema.FieldType.map(
            icebergTypeToBeamFieldType(type.asMapType().keyType(), updateCompatibilityVersion),
            icebergTypeToBeamFieldType(type.asMapType().valueType(), updateCompatibilityVersion));
      default:
        throw new RuntimeException("Unrecognized Iceberg Type: " + type.typeId());
    }
  }

  private static Schema.Field icebergFieldToBeamField(
      final Types.NestedField field, @Nullable String updateCompatibilityVersion) {
    return Schema.Field.of(
            field.name(), icebergTypeToBeamFieldType(field.type(), updateCompatibilityVersion))
        .withNullable(field.isOptional());
  }

  /** Converts an Iceberg {@link org.apache.iceberg.Schema} to a Beam {@link Schema}. */
  public static Schema icebergSchemaToBeamSchema(final org.apache.iceberg.Schema schema) {
    return icebergSchemaToBeamSchema(schema, null);
  }

  /**
   * Converts an Iceberg {@link org.apache.iceberg.Schema} to a Beam {@link Schema}, accounting for
   * update compatibility.

View on GitHub (pinned to 12126d8942)

Solutions

1. Alter the table schema to use a supported type (e.g. store UUID as string/fixed).
2. Upgrade Beam to a version whose IcebergUtils supports the type in question.
3. Project only supported columns in the read and transform unsupported ones downstream.
4. Replicate/re-write the table with a fully supported schema.

Example fix

// before (Iceberg schema)
uuid_col: uuid

// after
uuid_col: string

for (Types.NestedField f : schema.columns()) {
  if (!SUPPORTED_TYPE_IDS.contains(f.type().typeId())) {
    throw new IllegalStateException("Unsupported Iceberg type: " + f.type().typeId());
  }
}

try {
  beamSchema = IcebergUtils.icebergSchemaToBeamSchema(tableSchema);
} catch (RuntimeException e) {
  LOG.error("Unconvertible Iceberg type: {}", e.getMessage());
}

When it happens

Trigger: Reading an Iceberg table whose schema contains a primitive type not covered by the converter (e.g. UUID or certain nested/unknown typeIds) — the default case at IcebergUtils.java:139 fires, also recursively via icebergFieldToBeamField.

Common situations: Tables written by other engines containing UUID or unsupported primitive columns; newer Iceberg type additions predating the converter; schema drift after adding exotic columns to a table.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Arrow schema conversion does not support Beam type '%s' for
• Unsupported type: {fieldType}
• Error processing struct to row: {e.getMessage()}
• Unsupported Timestamp precision: {precision}
• Unsupported Beam logical type {logicalTypeIdentifier}

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/914fd6012cfbb4fc. Report an issue: GitHub.