{"record":{"id":"e96b2de29a923e65","repo":"apache/beam","slug":"encountered-an-unsupported-type-field-type-r","errorCode":null,"errorMessage":"Encountered an unsupported type: {field['type']!r}","messagePattern":"Encountered an unsupported type: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/gcp/bigquery_schema_tools.py","lineNumber":86,"sourceCode":"      BIG_QUERY_TO_PYTHON_TYPES. For example:\n      ``{'DATE': datetime.date, 'JSON': dict}``\n\n  Returns:\n    type: type that can be used to work with pCollections.\n  \"\"\"\n  effective_types = {**BIG_QUERY_TO_PYTHON_TYPES, **(type_overrides or {})}\n  the_schema = beam.io.gcp.bigquery_tools.get_dict_table_schema(\n      the_table_schema)\n  if the_schema == {}:\n    raise ValueError(\"Encountered an empty schema\")\n  field_names_and_types = []\n  for field in the_schema['fields']:\n    if selected_fields is not None and field['name'] not in selected_fields:\n      continue\n    if field['type'] in effective_types:\n      typ = bq_field_to_type(field['type'], field['mode'], type_overrides)\n    else:\n      raise ValueError(\n          f\"Encountered \"\n          f\"an unsupported type: {field['type']!r}\")\n    field_names_and_types.append((field['name'], typ))\n  sample_schema = beam.typehints.schemas.named_fields_to_schema(\n      field_names_and_types)\n  usertype = beam.typehints.schemas.named_tuple_from_schema(sample_schema)\n  return usertype\n\n\ndef bq_field_to_type(field, mode, type_overrides=None):\n  \"\"\"Convert a BigQuery field type and mode to a Python type hint.\n\n  Args:\n    field: The BigQuery type name (e.g., 'STRING', 'DATE').\n    mode: The field mode ('NULLABLE', 'REPEATED', 'REQUIRED').\n    type_overrides: Optional mapping of BigQuery type names (uppercase)\n      to Python types. These override the default mappings.\n","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/gcp/bigquery_schema_tools.py#L68-L104","documentation":"Raised by generate_user_type_from_bq_schema when a field in the BigQuery table schema has a 'type' not present in effective_types (the set of BigQuery types Beam can map to a Python user type). Beam refuses to guess a mapping and fails fast rather than producing a wrong namedtuple schema.","triggerScenarios":"Calling convert_to_usertype(table_schema) (directly or from WriteToBigQuery schema conversion) with a schema containing a field whose type is not one of the supported effective_types and for which no type_overrides entry maps it to a concrete Python type.","commonSituations":"Schemas using newer/less common BQ types like GEOGRAPHY, JSON, INTERVAL, or RANGE with older Beam versions; custom or hand-written JSON schemas with typos like 'STRINGG'; passing table schema fields like TIMESTAMP before overrides were configured.","solutions":["Add a type_overrides entry mapping the offending field name to a concrete Python type, e.g. {'geo': bytes} or {'j': str}.","Upgrade apache-beam to a version whose effective_types includes the new BigQuery type (GEOGRAPHY/JSON support was added over time).","Fix typos in hand-authored schema JSON so field['type'] matches a valid BigQuery type name.","Pre-process the schema to drop or transform unsupported fields before calling convert_to_usertype."],"exampleFix":"# before\nconvert_to_usertype(table_schema)  # schema has GEOGRAPHY field\n\n# after\nconvert_to_usertype(table_schema, type_overrides={'location': bytes})","handlingStrategy":"validation","validationCode":"SUPPORTED = {'STRING','BYTES','INTEGER','INT64','FLOAT','FLOAT64','NUMERIC','BIGNUMERIC','BOOLEAN','BOOL','TIMESTAMP','DATE','TIME','DATETIME','RECORD','STRUCT'}\nfor f in schema['fields']:\n    if f['type'] not in SUPPORTED and f['name'] not in (type_overrides or {}):\n        raise ValueError(f\"unsupported BQ type {f['type']!r} for field {f['name']!r}: add a type_overrides entry\")","typeGuard":"def is_supported_field(field, overrides=None):\n    return field.get('type') in SUPPORTED_TYPES or (overrides or {}).get(field.get('name')) is not None","tryCatchPattern":"try:\n    usertype = convert_to_usertype(schema, type_overrides=overrides)\nexcept ValueError as e:\n    log.error('schema conversion failed: %s', e)\n    raise","preventionTips":["Pin the apache-beam version and check its effective_types before adopting new BQ types","Always supply type_overrides for GEOGRAPHY/JSON/RANGE-style fields","Lint schema JSON against the canonical BigQuery type list"],"tags":["bigquery","schema","type-mapping","python"],"backgroundTag":"unsupported-enum-value","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"}