apache/beam · error · ValueError

Table schema must be of the type bigquery.TableSchema

Error message

Table schema must be of the type bigquery.TableSchema

What it means

table_schema_to_dict() requires a google.cloud.bigquery.table_schema.TableSchema object and raises ValueError for anything else. It recursively converts a typed TableSchema into a plain dict, so it deliberately rejects dicts, JSON strings, or other schema representations.

Source

Thrown at sdks/python/apache_beam/io/gcp/bigquery_tools.py:1717

def table_schema_to_dict(table_schema):
  """Create a dictionary representation of table schema for serialization
  """
  def get_table_field(field):
    """Create a dictionary representation of a table field
    """
    result = {}
    result['name'] = field.name
    result['type'] = field.type
    result['mode'] = getattr(field, 'mode', 'NULLABLE')
    if hasattr(field, 'description') and field.description is not None:
      result['description'] = field.description
    if hasattr(field, 'fields') and field.fields:
      result['fields'] = [get_table_field(f) for f in field.fields]
    return result

  if not isinstance(table_schema, bigquery.TableSchema):
    raise ValueError("Table schema must be of the type bigquery.TableSchema")
  schema = {'fields': []}
  for field in table_schema.fields:
    schema['fields'].append(get_table_field(field))
  return schema


def get_dict_table_schema(schema):
  """Transform the table schema into a dictionary instance.

  Args:
    schema (str, dict, ~apache_beam.io.gcp.internal.clients.bigquery.\
bigquery_v2_messages.TableSchema):
      The schema to be used if the BigQuery table to write has to be created.
      This can either be a dict or string or in the TableSchema format.

  Returns:
    Dict[str, Any]: The schema to be used if the BigQuery table to write has
    to be created but in the dictionary format.

View on GitHub (pinned to 12126d8942)

Solutions

1. Convert the input first: if it is a dict/str, call get_bq_tableschema(schema) to obtain a bigquery.TableSchema, then pass that to table_schema_to_dict.
2. Prefer get_dict_table_schema(schema), which dispatches on type and accepts str, dict, or TableSchema.
3. Ensure you import TableSchema from google.cloud.bigquery (or apache_beam.io.gcp.internal.clients.bigquery as appropriate) and construct it properly.

Example fix

// before
table_schema_to_dict({"fields": [...]})  # ValueError

// after
from apache_beam.io.gcp.bigquery_tools import get_dict_table_schema
schema_dict = get_dict_table_schema({"fields": [...]})

from google.cloud.bigquery.table_schema import TableSchema
if not isinstance(table_schema, TableSchema):
    table_schema = get_bq_tableschema(table_schema)

def is_tableschema(s):
    return isinstance(s, bigquery.TableSchema)

try:
    d = table_schema_to_dict(schema)
except (ValueError, TypeError):
    d = get_dict_table_schema(schema)  # dispatches on type

When it happens

Trigger: Passing a dict or JSON string schema directly to table_schema_to_dict() instead of a bigquery.TableSchema instance; passing the output of get_table_schema_from_string incorrectly; calling it with a legacy TableFieldSchema.

Common situations: Users loading a schema from JSON and forgetting to convert it; mixing up get_dict_table_schema (which accepts multiple forms) with table_schema_to_dict (which accepts only TableSchema); API version changes where schema classes moved packages.

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

• Unexpected schema argument: %s.
• Unexpected schema argument: %s.
• %s: gcs_location must be of type string or ValueProvider; go
• Both a query and an output type of 'BEAM_ROW' were specified
• %s: table must be of type string; got a callable instead

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