{"record":{"id":"9ffdb656eff7513f","repo":"apache/beam","slug":"unknown-bigquery-field-mode-s","errorCode":null,"errorMessage":"Unknown BigQuery Field Mode: %s","messagePattern":"Unknown BigQuery Field Mode: (.+?)","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/BigQueryAvroUtils.java","lineNumber":568,"sourceCode":"  private static Field convertField(\n      TableFieldSchema bigQueryField, Boolean useAvroLogicalTypes, @Nullable String namespace) {\n    String fieldName = bigQueryField.getName();\n    Schema fieldSchema;\n    String bqType = bigQueryField.getType();\n    if (\"RECORD\".equals(bqType) || \"STRUCT\".equals(bqType)) {\n      fieldSchema =\n          toGenericAvroSchema(fieldName, bigQueryField.getFields(), useAvroLogicalTypes, namespace);\n    } else {\n      fieldSchema = getPrimitiveType(bigQueryField, useAvroLogicalTypes);\n    }\n\n    String bqMode = bigQueryField.getMode();\n    if (bqMode == null || \"NULLABLE\".equals(bqMode)) {\n      fieldSchema = SchemaBuilder.unionOf().nullType().and().type(fieldSchema).endUnion();\n    } else if (\"REPEATED\".equals(bqMode)) {\n      fieldSchema = SchemaBuilder.array().items(fieldSchema);\n    } else if (!\"REQUIRED\".equals(bqMode)) {\n      throw new IllegalArgumentException(String.format(\"Unknown BigQuery Field Mode: %s\", bqMode));\n    }\n    // The Avro Field constructor accepts a null default value, but Avro is not annotated.\n    @SuppressWarnings(\"nullness\")\n    Field field =\n        new Field(\n            fieldName,\n            fieldSchema,\n            bigQueryField.getDescription(),\n            (Object) null /* Cast to avoid deprecated JsonNode constructor. */);\n    return field;\n  }\n\n  static TableSchema fromGenericAvroSchema(Schema schema) {\n    return fromGenericAvroSchema(schema, true);\n  }\n\n  static TableSchema fromGenericAvroSchema(Schema schema, Boolean useAvroLogicalTypes) {\n    verify(","sourceCodeStart":550,"sourceCodeEnd":586,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryAvroUtils.java#L550-L586","documentation":"When converting a BigQuery TableFieldSchema to an Avro Field, convertField validates the field mode. Only NULLABLE (or null), REQUIRED, and REPEATED are valid BigQuery modes; anything else throws IllegalArgumentException, since BigQuery itself only defines these three modes.","triggerScenarios":"toGenericAvroSchema receives a TableSchema whose field has a mode string other than NULLABLE/REQUIRED/REPEATED — typically from a hand-built TableSchema with a typo (e.g. \"REPEATABLE\", \"OPTIONAL\") or a corrupted API response.","commonSituations":"Manually constructed TableSchema/field descriptors in pipeline code or tests; third-party metadata that mislabels field modes.","solutions":["Fix the mode string to one of NULLABLE, REQUIRED, REPEATED (or omit it, defaulting to NULLABLE)","Validate TableSchema fields before building the Avro schema","Regenerate the schema from BigQuery's table metadata API rather than hand-writing it"],"exampleFix":"// before\nnew TableFieldSchema().setName(\"tags\").setType(\"STRING\").setMode(\"REPEATABLE\")\n// after\nnew TableFieldSchema().setName(\"tags\").setType(\"STRING\").setMode(\"REPEATED\")","handlingStrategy":"validation","validationCode":"String mode = field.getMode();\nif (mode != null && !Set.of(\"NULLABLE\",\"REQUIRED\",\"REPEATED\").contains(mode)) throw new IllegalArgumentException(\"Bad field mode \" + mode);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use BigQuery's metadata API to source modes instead of hand-writing them","Validate TableSchema in tests","Remember mode defaults to NULLABLE when omitted"],"tags":["java","apache-beam","bigquery","avro","schema","field-mode"],"backgroundTag":"invalid-enum-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}