{"record":{"id":"9fb8e344f78b8058","repo":"apache/beam","slug":"cannot-convert-beam-logical-type-to-bigquery-type","errorCode":null,"errorMessage":"Cannot convert Beam logical type:  to BigQuery type.","messagePattern":"Cannot convert Beam logical type:  to BigQuery type\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryUtils.java","lineNumber":367,"sourceCode":"\n  private static final String BIGQUERY_MAP_KEY_FIELD_NAME = \"key\";\n  private static final String BIGQUERY_MAP_VALUE_FIELD_NAME = \"value\";\n\n  /**\n   * Get the corresponding BigQuery {@link StandardSQLTypeName} for supported Beam {@link\n   * FieldType}.\n   */\n  static StandardSQLTypeName toStandardSQLTypeName(FieldType fieldType) {\n    StandardSQLTypeName ret;\n    if (fieldType.getTypeName().isLogicalType()) {\n      Schema.LogicalType<?, ?> logicalType =\n          Preconditions.checkArgumentNotNull(fieldType.getLogicalType());\n      ret = BEAM_TO_BIGQUERY_LOGICAL_MAPPING.get(logicalType.getIdentifier());\n      if (ret == null) {\n        if (logicalType instanceof PassThroughLogicalType) {\n          return toStandardSQLTypeName(logicalType.getBaseType());\n        }\n        throw new IllegalArgumentException(\n            \"Cannot convert Beam logical type: \"\n                + logicalType.getIdentifier()\n                + \" to BigQuery type.\");\n      }\n    } else {\n      ret = BEAM_TO_BIGQUERY_TYPE_MAPPING.get(fieldType.getTypeName());\n      if (ret == null) {\n        throw new IllegalArgumentException(\n            \"Cannot convert Beam type: \" + fieldType.getTypeName() + \" to BigQuery type.\");\n      }\n    }\n    return ret;\n  }\n\n  /**\n   * Represents a timestamp with picosecond precision, split into seconds and picoseconds\n   * components.\n   */","sourceCodeStart":349,"sourceCodeEnd":385,"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#L349-L385","documentation":"BigQueryUtils.toStandardSQLTypeName converts a Beam Schema FieldType to a BigQuery STANDARD_SQL type name. For logical types it looks up BEAM_TO_BIGQUERY_LOGICAL_MAPPING by the logical type identifier; if not found, it falls back to the PassThroughLogicalType base type, and otherwise throws IllegalArgumentException naming the identifier. It means Beam's schema contained a logical type BigQuery IO doesn't know how to map.","triggerScenarios":"Writing a PCollection with a Beam schema containing a custom LogicalType (or a logical type added in a newer Beam version, e.g. new type extensions) to BigQuery via BigQueryIO.writeTableRows / getFileLoads / StorageWrite where the type has no mapping and is not a PassThroughLogicalType.","commonSituations":"Custom user-defined LogicalType registered in the schema; Beam upgrade where new logical types (e.g. new monetary/uuid variants) aren't yet mapped to BigQuery; using Schema-aware transforms with exotic field types like EnumerationLogicalType.","solutions":["Map the field to a supported base type before writing (e.g. convert the logical type to its underlying primitive via withLogicalType/into base representation)","Register the logical type as a PassThroughLogicalType so the fallback to its base type kicks in","Upgrade Beam to the latest version — the BEAM_TO_BIGQUERY_LOGICAL_MAPPING grows over time","Pre-convert exotic fields to strings/bytes/primitives in a ParDo/Select before the BigQuery sink"],"exampleFix":"// before\nSchema schema = Schema.builder().addField(\"id\", logicalUUIDType).build(); // unmapped logical type\n// after\nSchema schema = Schema.builder().addStringField(\"id\").build(); // convert UUID to STRING first\nString id = myUuid.getValue().toString(); // drop the logical wrapper before writing","handlingStrategy":"validation","validationCode":"for (Field f : schema.getFields()) {\n  if (f.getType().getTypeName() == TypeName.LOGICAL_TYPE) {\n    LogicalType lt = f.getType().getLogicalType();\n    if (!(lt instanceof PassThroughLogicalType)) {\n      throw new IllegalArgumentException(\"Unmapped logical type for BigQuery: \" + lt.getIdentifier());\n    }\n  }\n}","typeGuard":"boolean bigQueryMappable(FieldType t) {\n  if (t.getTypeName() != TypeName.LOGICAL_TYPE) return true;\n  return t.getLogicalType() instanceof PassThroughLogicalType; // plus known mapped identifiers\n}","tryCatchPattern":"try {\n  rows.apply(BigQueryIO.writeTableRows().to(spec));\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"Cannot convert Beam logical type\")) {\n    // apply a schema transform converting the field to its base type, then retry\n  } else throw e;\n}","preventionTips":["Convert custom logical types to their base/primitive representation before writing","Prefer PassThroughLogicalType for passthrough customs so the base-type fallback applies","Upgrade Beam when using recently added logical types","Validate pipeline schema against BigQuery-supported types in a unit test"],"tags":["bigquery","beam-schema","logical-type","type-mapping"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}