apache/beam · error · IllegalArgumentException

Unknown BigQuery Field Mode: %s

Error message

Unknown BigQuery Field Mode: %s

What it means

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.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryAvroUtils.java:568

  private static Field convertField(
      TableFieldSchema bigQueryField, Boolean useAvroLogicalTypes, @Nullable String namespace) {
    String fieldName = bigQueryField.getName();
    Schema fieldSchema;
    String bqType = bigQueryField.getType();
    if ("RECORD".equals(bqType) || "STRUCT".equals(bqType)) {
      fieldSchema =
          toGenericAvroSchema(fieldName, bigQueryField.getFields(), useAvroLogicalTypes, namespace);
    } else {
      fieldSchema = getPrimitiveType(bigQueryField, useAvroLogicalTypes);
    }

    String bqMode = bigQueryField.getMode();
    if (bqMode == null || "NULLABLE".equals(bqMode)) {
      fieldSchema = SchemaBuilder.unionOf().nullType().and().type(fieldSchema).endUnion();
    } else if ("REPEATED".equals(bqMode)) {
      fieldSchema = SchemaBuilder.array().items(fieldSchema);
    } else if (!"REQUIRED".equals(bqMode)) {
      throw new IllegalArgumentException(String.format("Unknown BigQuery Field Mode: %s", bqMode));
    }
    // The Avro Field constructor accepts a null default value, but Avro is not annotated.
    @SuppressWarnings("nullness")
    Field field =
        new Field(
            fieldName,
            fieldSchema,
            bigQueryField.getDescription(),
            (Object) null /* Cast to avoid deprecated JsonNode constructor. */);
    return field;
  }

  static TableSchema fromGenericAvroSchema(Schema schema) {
    return fromGenericAvroSchema(schema, true);
  }

  static TableSchema fromGenericAvroSchema(Schema schema, Boolean useAvroLogicalTypes) {
    verify(

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the mode string to one of NULLABLE, REQUIRED, REPEATED (or omit it, defaulting to NULLABLE)
2. Validate TableSchema fields before building the Avro schema
3. Regenerate the schema from BigQuery's table metadata API rather than hand-writing it

Example fix

// before
new TableFieldSchema().setName("tags").setType("STRING").setMode("REPEATABLE")
// after
new TableFieldSchema().setName("tags").setType("STRING").setMode("REPEATED")

String mode = field.getMode();
if (mode != null && !Set.of("NULLABLE","REQUIRED","REPEATED").contains(mode)) throw new IllegalArgumentException("Bad field mode " + mode);

When it happens

Trigger: 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.

Common situations: Manually constructed TableSchema/field descriptors in pipeline code or tests; third-party metadata that mislabels field modes.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Reserved field name <field.name()> in user schema.
• RECORD/STRUCT are not primitive types
• Unknown BigQuery type: " + bqType
• Unknown Avro type: " + type.getType()
• Unsupported type <elementType.getType()>

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/9ffdb656eff7513f. Report an issue: GitHub.