{"record":{"id":"1dbfc52e5e8d9fe8","repo":"apache/beam","slug":"cannot-convert-bigquery-type-to-because-the-bigquery-type-is","errorCode":null,"errorMessage":"Cannot convert BigQuery type '' to '' because the BigQuery type is a List, while the output type is not a collection.","messagePattern":"Cannot convert BigQuery type '' to '' because the BigQuery type is a List, while the output type is not a collection\\.","errorType":"exception","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":959,"sourceCode":"      } else if (fieldType.isLogicalType(Timestamp.IDENTIFIER)) {\n        if (!jsonBQString.contains(\"UTC\")) {\n          BigDecimal bd = new BigDecimal(jsonBQString);\n          long seconds = bd.longValue();\n          long nanos = bd.subtract(BigDecimal.valueOf(seconds)).movePointRight(9).longValue();\n          return java.time.Instant.ofEpochSecond(seconds, nanos);\n        }\n        return VAR_PRECISION_FORMATTER.parse(jsonBQString, java.time.Instant::from);\n      }\n    }\n\n    if (jsonBQValue instanceof byte[] && fieldType.getTypeName() == TypeName.BYTES) {\n      return jsonBQValue;\n    }\n\n    if (jsonBQValue instanceof List) {\n      FieldType collectionElementType = fieldType.getCollectionElementType();\n      if (collectionElementType == null) {\n        throw new IllegalArgumentException(\n            \"Cannot convert BigQuery type '\"\n                + jsonBQValue.getClass()\n                + \"' to '\"\n                + fieldType\n                + \"' because the BigQuery type is a List, while the output type is not a\"\n                + \" collection.\");\n      }\n\n      boolean innerTypeIsMap = collectionElementType.getTypeName().isMapType();\n\n      return ((List<@Nullable Object>) jsonBQValue)\n          .stream()\n              // Old BigQuery client returns arrays as lists of maps {\"v\": <value>}.\n              // If this is the case, unwrap the value first\n              .<@Nullable Object>map(\n                  v ->\n                      (!innerTypeIsMap\n                              && v instanceof Map","sourceCodeStart":941,"sourceCodeEnd":977,"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#L941-L977","documentation":"Thrown in BigQueryUtils.fromJsonToBeamField when the BigQuery JSON value is a List (a BigQuery ARRAY/REPEATED field) but the target Beam FieldType has no collection element type, i.e. the Beam schema says the field is not an array. The message interpolates the value's Java class and the FieldType. It signals a schema mismatch between the BigQuery source and the declared Beam Row schema.","triggerScenarios":"toBeamRow conversion encountering a repeated BigQuery column (JSON array value) mapped to a Beam FieldType that is not FieldType.array(...) (getCollectionElementType() == null).","commonSituations":"Hand-written Beam schema where a REPEATED BigQuery column was declared as a scalar; table schema changed a column from scalar to ARRAY after the pipeline schema was written; using a generic FieldType for a field that BigQuery returns as a list.","solutions":["Declare the field as an array in the Beam schema: FieldType.array(FieldType.STRING) matching the BigQuery REPEATED type.","Regenerate the Beam schema from the actual table schema with BigQueryUtils.fromTableSchema(...) so REPEATED columns become arrays.","If the field should be scalar, flatten the BigQuery value upstream (UNNEST or take [SAFE_ORDINAL]) before conversion.","Verify the target FieldType actually corresponds to the BigQuery column type for that field name."],"exampleFix":"// before\nField f = Field.of(\"tags\", FieldType.STRING); // BigQuery REPEATED<STRING>\n\n// after\nField f = Field.of(\"tags\", FieldType.array(FieldType.STRING));","handlingStrategy":"validation","validationCode":"// Java: ensure every List-valued JSON field maps to an array FieldType\nschema.getFields().forEach(f -> {\n  Object v = tableRow.get(f.getName());\n  if (v instanceof List && f.getType().getCollectionElementType() == null) {\n    throw new IllegalArgumentException(\"Field must be array-typed: \" + f.getName());\n  }\n});","typeGuard":"// Java\nstatic boolean listValueHasArrayType(TableRow tr, Schema.Field f) {\n  return !(tr.get(f.getName()) instanceof List) || f.getType().getCollectionElementType() != null;\n}","tryCatchPattern":"try {\n  Row row = BigQueryUtils.toBeamRow(schema, tableRow);\n} catch (IllegalArgumentException e) {\n  // inspect schema mismatch reported in message; route to dead-letter\n}","preventionTips":["Map every REPEATED BigQuery column to FieldType.array(elementType) in the Beam schema.","Diff the Beam schema against the table schema at pipeline startup (fail fast on drift).","Beware of table schema changes turning scalar columns into ARRAY columns."],"tags":["java","apache-beam","bigquery","type-mismatch","array"],"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"}