apache/beam · error · IllegalArgumentException

Cannot convert Beam type: to BigQuery type.

Error message

Cannot convert Beam type:  to BigQuery type.

What it means

In BigQueryUtils.toStandardSQLTypeName, non-logical field types are looked up in BEAM_TO_BIGQUERY_TYPE_MAPPING by TypeName. If the mapping has no entry (the Beam primitive/array/map/iterable type has no BigQuery equivalent), an IllegalArgumentException is thrown. This guards against attempting to write schema fields BigQuery IO cannot represent.

Solutions

1. Flatten or simplify unsupported nested types before writing (avoid list<list<T>>; BigQuery only supports one level of nesting)
2. Convert unmapped fields to supported primitives (STRING/BYTES/INT64/FLOAT64/NUMERIC/TIMESTAMP/etc.) in a Select/ParDo
3. Upgrade Beam to pick up additions to BEAM_TO_BIGQUERY_TYPE_MAPPING
4. Inspect the schema (pcollection.getSchema()) and validate every field type against BigQuery-supported types before the sink

Example fix

// before
Schema.builder().addArrayField("matrix", FieldType.array(FieldType.INT64)).build(); // nested array
// after
// flatten: one level of array only, or encode as repeated struct / JSON string
Schema.builder().addArrayField("values", FieldType.INT64).build();
// or
Schema.builder().addStringField("matrixJson").build(); // serialize nested structure to JSON

static final Set<TypeName> SUPPORTED = Set.of(TypeName.BYTE, TypeName.INT16, TypeName.INT32,
    TypeName.INT64, TypeName.FLOAT, TypeName.DOUBLE, TypeName.DECIMAL, TypeName.STRING,
    TypeName.DATETIME, TypeName.BOOLEAN, TypeName.BYTES, TypeName.ARRAY, TypeName.ROW);
for (Field f : schema.getFields()) {
  if (!SUPPORTED.contains(f.getType().getTypeName())) {
    throw new IllegalArgumentException("Unsupported Beam type for BigQuery: " + f.getType().getTypeName());
  }
}

boolean bigQuerySupported(FieldType t) {
  return BEAM_TO_BIGQUERY_TYPE_MAPPING.containsKey(t.getTypeName()); // conceptually; validate recursively
}

try {
  rows.apply(BigQueryIO.writeTableRows().to(spec));
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Cannot convert Beam type")) {
    // reshape the schema (flatten nesting, serialize to STRING) and retry
  } else throw e;
}

When it happens

Trigger: Writing a PCollection whose schema contains a Beam type absent from BEAM_TO_BIGQUERY_TYPE_MAPPING (e.g. nested BYTES in unsupported position, DATETIME variants, unspecified/EXUPPORTED types) to a BigQuery sink.

Common situations: Nested collections (list<list<T>>) unsupported by BigQuery; map types with unsupported key/value types; new Beam TypeName added in a newer Beam than the mapping table; passing generic ROW without proper nested conversion.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Cannot convert Beam logical type: to BigQuery type.
• Cannot cast to a compatible object to build ByteString.
• Converting BigQuery type
• Converting BigQuery type
• Converting BigQuery type '' to '' is not supported

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

Appendix: source

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

  static StandardSQLTypeName toStandardSQLTypeName(FieldType fieldType) {
    StandardSQLTypeName ret;
    if (fieldType.getTypeName().isLogicalType()) {
      Schema.LogicalType<?, ?> logicalType =
          Preconditions.checkArgumentNotNull(fieldType.getLogicalType());
      ret = BEAM_TO_BIGQUERY_LOGICAL_MAPPING.get(logicalType.getIdentifier());
      if (ret == null) {
        if (logicalType instanceof PassThroughLogicalType) {
          return toStandardSQLTypeName(logicalType.getBaseType());
        }
        throw new IllegalArgumentException(
            "Cannot convert Beam logical type: "
                + logicalType.getIdentifier()
                + " to BigQuery type.");
      }
    } else {
      ret = BEAM_TO_BIGQUERY_TYPE_MAPPING.get(fieldType.getTypeName());
      if (ret == null) {
        throw new IllegalArgumentException(
            "Cannot convert Beam type: " + fieldType.getTypeName() + " to BigQuery type.");
      }
    }
    return ret;
  }

  /**
   * Represents a timestamp with picosecond precision, split into seconds and picoseconds
   * components.
   */
  public static class TimestampPicos {
    final long seconds;
    final long picoseconds;

    TimestampPicos(long seconds, long picoseconds) {
      this.seconds = seconds;
      this.picoseconds = picoseconds;
    }

View on GitHub (pinned to 12126d8942)