{"record":{"id":"0cfb72b9ded448dd","repo":"apache/beam","slug":"unknown-logical-type-identifier","errorCode":null,"errorMessage":"Unknown logical type \" + identifier","messagePattern":"Unknown logical type \" \\+ identifier","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryUtils.java","lineNumber":1073,"sourceCode":"        } else if (SqlTypes.TIME.getIdentifier().equals(identifier)) {\n          return convertAvroTime(avroValue);\n        } else if (SqlTypes.DATETIME.getIdentifier().equals(identifier)) {\n          return convertAvroDateTime(avroValue);\n        } else if (SQL_DATE_TIME_TYPES.contains(identifier)) {\n          switch (options.getTruncateTimestamps()) {\n            case TRUNCATE:\n              return truncateToMillis(avroValue);\n            case REJECT:\n              return safeToMillis(avroValue);\n            default:\n              throw new IllegalArgumentException(\n                  String.format(\n                      \"Unknown timestamp truncation option: %s\", options.getTruncateTimestamps()));\n          }\n        } else if (logicalType instanceof PassThroughLogicalType) {\n          return convertAvroFormat(logicalType.getBaseType(), avroValue, options);\n        } else {\n          throw new RuntimeException(\"Unknown logical type \" + identifier);\n        }\n      case ROW:\n        Schema rowSchema = beamFieldType.getRowSchema();\n        if (rowSchema == null) {\n          throw new IllegalArgumentException(\"Nested ROW missing row schema\");\n        }\n        GenericData.Record record = (GenericData.Record) avroValue;\n        return toBeamRow(record, rowSchema, options);\n      case MAP:\n        return convertAvroRecordToMap(beamFieldType, avroValue, options);\n      default:\n        throw new RuntimeException(\n            \"Does not support converting unknown type value: \" + beamFieldTypeName);\n    }\n  }\n\n  private static ReadableInstant safeToMillis(Object value) {\n    long subMilliPrecision = ((long) value) % 1000;","sourceCodeStart":1055,"sourceCodeEnd":1091,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryUtils.java#L1055-L1091","documentation":"Thrown as a RuntimeException when convertAvroFormat encounters a Beam LOGICAL_TYPE field whose identifier is not DATE, TIME, DATETIME, a known SQL date-time type, or a PassThroughLogicalType. Beam's BigQuery Avro converter simply has no mapping for that logical type identifier, so it refuses to convert. Usually indicates schema drift or a logical type added in a newer Beam than the running code.","triggerScenarios":"BigQueryIO.readTableRows over Avro records whose Beam schema field has a custom/unrecognized logical type identifier — e.g. a schema produced by a newer Beam version with logical types this converter doesn't know, or user-defined logical types on ROW fields.","commonSituations":"Beam version skew (newer producer schema, older consumer); user-defined LogicalType subclasses that don't extend PassThroughLogicalType; schemas round-tripped through systems adding custom logical types.","solutions":["Upgrade the Beam SDK to the version that supports the logical type identifier in the error message.","Make the custom LogicalType extend PassThroughLogicalType so its base type is converted instead.","Change the field to a standard supported type (DATE/TIME/DATETIME or primitive) in the Beam schema.","Strip or remap unknown logical types from the schema before the BigQueryIO avro conversion."],"exampleFix":"// before\npublic class MyType implements LogicalType<...> { /* custom identifier */ }\n// after\npublic class MyType extends PassThroughLogicalType<String> { /* base type converted instead */ }","handlingStrategy":"validation","validationCode":"// Java: pre-check every logical type is supported before reading\nfor (Field f : schema.getFields()) {\n  if (f.getType().getTypeName() == TypeName.LOGICAL_TYPE) {\n    String id = f.getType().getLogical().getIdentifier();\n    boolean supported = id.equals(\"DATE\") || id.equals(\"TIME\") || id.equals(\"DATETIME\")\n        || f.getType().getLogical() instanceof PassThroughLogicalType;\n    if (!supported) throw new IllegalStateException(\"Unsupported logical type: \" + id);\n  }\n}","typeGuard":"// Java\nstatic boolean isSupportedLogicalType(FieldType t) {\n  return t.getTypeName() != TypeName.LOGICAL_TYPE\n      || t.getLogical() instanceof PassThroughLogicalType\n      || Set.of(\"DATE\", \"TIME\", \"DATETIME\").contains(t.getLogical().getIdentifier());\n}","tryCatchPattern":"try { rows = pipeline.apply(BigQueryIO.readTableRows()...); } catch (RuntimeException e) { if (e.getMessage().startsWith(\"Unknown logical type\")) { log.error(\"Upgrade Beam or map logical type: {}\", e.getMessage()); } throw e; }","preventionTips":["Prefer standard DATE/TIME/DATETIME fields over custom logical types in Beam schemas feeding BigQueryIO.","Make custom LogicalTypes extend PassThroughLogicalType.","Upgrade Beam when the schema contains newer logical type identifiers."],"tags":["java","beam","bigquery","avro","logical-type","schema"],"backgroundTag":"unsupported-operation","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"}