Found JSON type in TableSchema for 'FILE_LOADS' write…

Error message

Found JSON type in TableSchema for 'FILE_LOADS' write method. 
 check steps in https://cloud.google.com/bigquery/docs/loading-data-cloud-storage-avro#extract_json_data_from_avro_data  to ensure the read as a JSON type. Otherwise it will read as a raw (escaped) string.

What it means

This is a log warning from BigQueryIO for FILE_LOADS writes using Avro output. When the table schema has JSON-typed fields and rows are serialized as AvroGenericRecord, Beam warns that special extraction steps must be followed or the JSON will be read back as raw escaped strings in BigQuery.

Solutions

Follow https://cloud.google.com/bigquery/docs/loading-data-cloud-storage-avro#extract_json_data_from_avro_data to encode JSON fields as strings in the Avro record so BigQuery can extract them.
Store JSON fields as STRING in the Avro schema and let BigQuery's extract step convert them to JSON type.
Switch output type to JsonTableRow with Jackson JsonNode values if Avro handling is too constrained.
Remove JSON types from the table schema (use STRING) if structured JSON access is not required.

Example fix

// before
record.put("payload", schema.getField("payload").schema()); // nested/complex Avro schema
// after
record.put("payload", "{\"a\":1}"); // JSON encoded as string, per BigQuery Avro extraction docs

Defensive patterns

Strategy: validation

Validate before calling

// Verify Avro output type when schema has JSON fields
if (schemaContainsJsonType(jsonSchemaString) && outputType != OutputType.JsonTableRow) {
  // encode JSON columns as strings per Avro extraction docs before writing
}

Type guard

boolean isGenericRecordOutput(Object writer) { return writer instanceof org.apache.avro.generic.GenericRecord; }

Prevention

Follow the BigQuery Avro JSON extraction documented steps when writing Avro.
Avoid JSON column types in schemas unless you control serialization end-to-end.
Test round-trip loads into a scratch dataset to confirm JSON parses as JSON, not escaped strings.

When it happens

Trigger: Using BigQueryIO write with withMethod(FILE_LOADS) and AvroGenericRecord output type where the destination schema (via withJsonSchema) contains JSON-type fields.

Common situations: Pipelines writing Avro records to BigQuery tables with JSON columns; migrating a pipeline from TableRow to Avro serialization without adjusting JSON handling; following BigQuery docs for extracting JSON from Avro data.

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

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

Appendix: source

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

          LOG.warn(
              "Error Handling is partially supported when using FILE_LOADS. Consider using STORAGE_WRITE_API or STORAGE_API_AT_LEAST_ONCE");
        }

        // Batch load handles wrapped json string value differently than the other methods. Raise a
        // warning when applies.
        ValueProvider<String> jsonSchema = getJsonSchema();
        if (jsonSchema != null && jsonSchema.isAccessible()) {
          JsonElement schema = JsonParser.parseString(jsonSchema.get());
          if (!schema.getAsJsonObject().keySet().isEmpty() && hasJsonTypeInSchema(schema)) {
            if (rowWriterFactory.getOutputType() == OutputType.JsonTableRow) {
              LOG.warn(
                  "Found JSON type in TableSchema for 'FILE_LOADS' write method. \n"
                      + "Make sure the TableRow value is a Jackson JsonNode to ensure the read as a "
                      + "JSON type. Otherwise it will read as a raw (escaped) string.\n"
                      + "See https://cloud.google.com/bigquery/docs/loading-data-cloud-storage-json#limitations "
                      + "for limitations.");
            } else if (rowWriterFactory.getOutputType() == OutputType.AvroGenericRecord) {
              LOG.warn(
                  "Found JSON type in TableSchema for 'FILE_LOADS' write method. \n"
                      + " check steps in https://cloud.google.com/bigquery/docs/loading-data-cloud-storage-avro#extract_json_data_from_avro_data "
                      + " to ensure the read as a JSON type. Otherwise it will read as a raw "
                      + "(escaped) string.");
            }
          }
        }

        BatchLoads<DestinationT, T> batchLoads =
            new BatchLoads<>(
                getWriteDisposition(),
                getCreateDisposition(),
                getJsonTableRef() != null,
                dynamicDestinations,
                destinationCoder,
                getCustomGcsTempLocation(),
                getLoadJobProjectId(),
                getIgnoreUnknownValues(),

View on GitHub (pinned to 12126d8942)