apache/beam · error · TypeError

Unexpected schema argument: %s.

Error message

Unexpected schema argument: %s.

What it means

get_table_schema converts the schema argument and only accepts None, a string (JSON), or a dict. Any other type (e.g. a pyarrow schema, an object, or a list) is rejected with TypeError so invalid schema inputs fail fast at setup time (_create_table_if_needed).

Source

Thrown at sdks/python/apache_beam/io/gcp/bigquery.py:1613

  def get_table_schema(schema):
    """Transform the table schema into a bigquery.TableSchema instance.

    Args:
      schema: The schema to be used if the BigQuery table to write has to be
        created. This is a dictionary object created in the WriteToBigQuery
        transform.
    Returns:
      table_schema: The schema to be used if the BigQuery table to write has
         to be created but in the bigquery.TableSchema format.
    """
    if schema is None:
      return schema
    elif isinstance(schema, str):
      return bigquery_tools.parse_table_schema_from_json(schema)
    elif isinstance(schema, dict):
      return bigquery_tools.parse_table_schema_from_json(json.dumps(schema))
    else:
      raise TypeError('Unexpected schema argument: %s.' % schema)

  def start_bundle(self):
    self._reset_rows_buffer()

    if not self.bigquery_wrapper:
      self.bigquery_wrapper = bigquery_tools.BigQueryWrapper(
          client=self.test_client)

    (
        bigquery_tools.BigQueryWrapper.HISTOGRAM_METRIC_LOGGER.
        minimum_logging_frequency_msec
    ) = self.streaming_api_logging_frequency_sec * 1000

    self._backoff_calculator = iter(
        retry.FuzzedExponentialIntervals(
            initial_delay_secs=0.2,
            num_retries=self._max_retries,
            max_delay_secs=1500))

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass the schema as a JSON string or a dict matching the BigQuery JSON schema format.
2. Convert other schema representations: pyarrow.Schema -> serialize to JSON, list of SchemaField -> bigquery_tools.get_table_schema or client's to_api_repr().
3. Use SCHEMA_AUTODETECT constant with FILE_LOADS if you want the schema inferred.

Example fix

// before
WriteToBigQuery(table, schema=pyarrow_schema)
// after
WriteToBigQuery(table, schema='{"fields": [{"name": "id", "type": "INTEGER"}]}')
# or schema={'fields': [{'name': 'id', 'type': 'INTEGER'}]}

assert schema is None or isinstance(schema, (str, dict)), f'schema must be None, JSON str, or dict, got {type(schema)}'

def valid_bq_schema(schema):
    return schema is None or isinstance(schema, (str, dict))

try:
    _ = beam.io.WriteToBigQuery(table, schema=schema)
except TypeError as e:
    schema = json.dumps(schema_to_json(schema))  # convert then retry

When it happens

Trigger: Passing schema as something other than str/dict/None to WriteToBigQuery — e.g. a bigquery.SchemaField list, a pyarrow.Schema, or an Apache Beam schema object.

Common situations: Reusing a schema obtained from the google-cloud-bigquery client or from a PCollection schema without converting it to the JSON string/dict form Beam expects.

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

• Both a query and an output type of 'BEAM_ROW' were specified
• Unknown BigQuery field mode: {}
• Table schema must be of the type bigquery.TableSchema
• Unexpected schema argument: %s.
• Converting BigQuery type [{field_type}] to Python Beam type

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