{"record":{"id":"914fd6012cfbb4fc","repo":"apache/beam","slug":"unrecognized-iceberg-type-typeid","errorCode":null,"errorMessage":"Unrecognized Iceberg Type: {typeId}","messagePattern":"Unrecognized Iceberg Type: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/IcebergUtils.java","lineNumber":139,"sourceCode":"      case UUID:\n      case BINARY:\n      case FIXED:\n        return Schema.FieldType.BYTES;\n      case DECIMAL:\n        return Schema.FieldType.DECIMAL;\n      case STRUCT:\n        return Schema.FieldType.row(\n            icebergStructTypeToBeamSchema(type.asStructType(), updateCompatibilityVersion));\n      case LIST:\n        return Schema.FieldType.array(\n            icebergTypeToBeamFieldType(\n                type.asListType().elementType(), updateCompatibilityVersion));\n      case MAP:\n        return Schema.FieldType.map(\n            icebergTypeToBeamFieldType(type.asMapType().keyType(), updateCompatibilityVersion),\n            icebergTypeToBeamFieldType(type.asMapType().valueType(), updateCompatibilityVersion));\n      default:\n        throw new RuntimeException(\"Unrecognized Iceberg Type: \" + type.typeId());\n    }\n  }\n\n  private static Schema.Field icebergFieldToBeamField(\n      final Types.NestedField field, @Nullable String updateCompatibilityVersion) {\n    return Schema.Field.of(\n            field.name(), icebergTypeToBeamFieldType(field.type(), updateCompatibilityVersion))\n        .withNullable(field.isOptional());\n  }\n\n  /** Converts an Iceberg {@link org.apache.iceberg.Schema} to a Beam {@link Schema}. */\n  public static Schema icebergSchemaToBeamSchema(final org.apache.iceberg.Schema schema) {\n    return icebergSchemaToBeamSchema(schema, null);\n  }\n\n  /**\n   * Converts an Iceberg {@link org.apache.iceberg.Schema} to a Beam {@link Schema}, accounting for\n   * update compatibility.","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/IcebergUtils.java#L121-L157","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Alter the table schema to use a supported type (e.g. store UUID as string/fixed).","Upgrade Beam to a version whose IcebergUtils supports the type in question.","Project only supported columns in the read and transform unsupported ones downstream.","Replicate/re-write the table with a fully supported schema."],"exampleFix":"// before (Iceberg schema)\nuuid_col: uuid\n\n// after\nuuid_col: string","handlingStrategy":"validation","validationCode":"for (Types.NestedField f : schema.columns()) {\n  if (!SUPPORTED_TYPE_IDS.contains(f.type().typeId())) {\n    throw new IllegalStateException(\"Unsupported Iceberg type: \" + f.type().typeId());\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  beamSchema = IcebergUtils.icebergSchemaToBeamSchema(tableSchema);\n} catch (RuntimeException e) {\n  LOG.error(\"Unconvertible Iceberg type: {}\", e.getMessage());\n}","preventionTips":["Restrict table schemas to primitive types Beam supports.","Store UUIDs as strings/fixed where possible.","Test read pipelines after any schema change on the table.","Upgrade Beam before relying on newly added Iceberg types."],"tags":["java","iceberg","type-conversion","schema"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}