apache/beam · error · IllegalArgumentException

Unknown BigQuery type: " + bqType

Error message

Unknown BigQuery type: " + bqType

What it means

getPrimitiveType throws IllegalArgumentException for BigQuery type names it does not recognize (including RANGE, currently unsupported). This guards against silently producing a wrong Avro primitive type when mapping BigQuery standard SQL types to Avro.

Source

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

        } else if (schema.getPrecision() != null) {
          logicalType = LogicalTypes.decimal(schema.getPrecision().intValue());
        } else if (bqType.equals("NUMERIC")) {
          logicalType = LogicalTypes.decimal(38, 9);
        } else {
          // BIGNUMERIC
          logicalType = LogicalTypes.decimal(77, 38);
        }
        return logicalType.addToSchema(SchemaBuilder.builder().bytesType());
      case "GEOGRAPHY":
      case "JSON":
        return SchemaBuilder.builder().stringBuilder().prop("sqlType", bqType).endString();
      case "RECORD":
      case "STRUCT":
        // record
        throw new IllegalArgumentException("RECORD/STRUCT are not primitive types");
      case "RANGE": // TODO add support for range type
      default:
        throw new IllegalArgumentException("Unknown BigQuery type: " + bqType);
    }
  }

  /**
   * Formats BigQuery seconds-since-epoch into String matching JSON export. Thread-safe and
   * immutable.
   */
  private static final java.time.format.DateTimeFormatter DATE_TIME_FORMATTER =
      java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")
          .withZone(java.time.ZoneOffset.UTC);

  /** Enum to define the precision of a timestamp since the epoch. */
  enum TimestampPrecision {
    MILLISECONDS,
    MICROSECONDS,
    NANOSECONDS;

    /** Converts an epoch value of this precision to an Instant. */

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade Apache Beam to a version supporting the type
2. Remove or transform the unsupported column (e.g. cast RANGE to STRING in SQL before the sink)
3. Fix the type string in the TableSchema if it was constructed manually

Example fix

// before
TableFieldSchema f = new TableFieldSchema().setName("r").setType("RANGE");
// after
TableFieldSchema f = new TableFieldSchema().setName("r").setType("STRING"); // CAST in query first

Set<String> known = Set.of("STRING","INTEGER","FLOAT","BOOLEAN","TIMESTAMP","DATE","TIME","DATETIME","NUMERIC","BIGNUMERIC","BYTES","GEOGRAPHY","JSON","INTERVAL");
if (!known.contains(field.getType())) throw new IllegalArgumentException("Unsupported BigQuery type " + field.getType());

When it happens

Trigger: convertField encounters a TableFieldSchema whose type is not in the supported set (STRING, INTEGER, FLOAT, BOOLEAN, TIMESTAMP, DATE, TIME, DATETIME, NUMERIC, GEOGRAPHY, JSON, BYTES, etc.), e.g. RANGE or a newly added BigQuery type, when generating an Avro schema from a TableSchema.

Common situations: Newer BigQuery types (e.g. RANGE) or typo'd type names in a user-constructed TableSchema; pipelines exporting/reading with beam BigQueryIO and newer BigQuery features.

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

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

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