{"record":{"id":"3a8e8b998236e860","repo":"apache/beam","slug":"table-schema-must-be-of-the-type-bigquery-tableschema","errorCode":null,"errorMessage":"Table schema must be of the type bigquery.TableSchema","messagePattern":"Table schema must be of the type bigquery\\.TableSchema","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/gcp/bigquery_tools.py","lineNumber":1717,"sourceCode":"\ndef table_schema_to_dict(table_schema):\n  \"\"\"Create a dictionary representation of table schema for serialization\n  \"\"\"\n  def get_table_field(field):\n    \"\"\"Create a dictionary representation of a table field\n    \"\"\"\n    result = {}\n    result['name'] = field.name\n    result['type'] = field.type\n    result['mode'] = getattr(field, 'mode', 'NULLABLE')\n    if hasattr(field, 'description') and field.description is not None:\n      result['description'] = field.description\n    if hasattr(field, 'fields') and field.fields:\n      result['fields'] = [get_table_field(f) for f in field.fields]\n    return result\n\n  if not isinstance(table_schema, bigquery.TableSchema):\n    raise ValueError(\"Table schema must be of the type bigquery.TableSchema\")\n  schema = {'fields': []}\n  for field in table_schema.fields:\n    schema['fields'].append(get_table_field(field))\n  return schema\n\n\ndef get_dict_table_schema(schema):\n  \"\"\"Transform the table schema into a dictionary instance.\n\n  Args:\n    schema (str, dict, ~apache_beam.io.gcp.internal.clients.bigquery.\\\nbigquery_v2_messages.TableSchema):\n      The schema to be used if the BigQuery table to write has to be created.\n      This can either be a dict or string or in the TableSchema format.\n\n  Returns:\n    Dict[str, Any]: The schema to be used if the BigQuery table to write has\n    to be created but in the dictionary format.","sourceCodeStart":1699,"sourceCodeEnd":1735,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/gcp/bigquery_tools.py#L1699-L1735","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Prefer get_dict_table_schema(schema), which dispatches on type and accepts str, dict, or TableSchema.","Ensure you import TableSchema from google.cloud.bigquery (or apache_beam.io.gcp.internal.clients.bigquery as appropriate) and construct it properly."],"exampleFix":"// before\ntable_schema_to_dict({\"fields\": [...]})  # ValueError\n\n// after\nfrom apache_beam.io.gcp.bigquery_tools import get_dict_table_schema\nschema_dict = get_dict_table_schema({\"fields\": [...]})","handlingStrategy":"type-guard","validationCode":"from google.cloud.bigquery.table_schema import TableSchema\nif not isinstance(table_schema, TableSchema):\n    table_schema = get_bq_tableschema(table_schema)","typeGuard":"def is_tableschema(s):\n    return isinstance(s, bigquery.TableSchema)","tryCatchPattern":"try:\n    d = table_schema_to_dict(schema)\nexcept (ValueError, TypeError):\n    d = get_dict_table_schema(schema)  # dispatches on type","preventionTips":["Prefer get_dict_table_schema(), which accepts str/dict/TableSchema, over the strict internal converter.","Normalize all schemas through get_bq_tableschema() early in your pipeline.","Don't mix schema classes from apache_beam.io.gcp.internal.clients.bigquery and google.cloud.bigquery."],"tags":["python","apache-beam","bigquery","schema","type-error"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}