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.

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": [...]})
Defensive patterns

Strategy: type-guard

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

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

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

Appendix: 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)