{"record":{"id":"25732df982e5cfd6","repo":"apache/beam","slug":"encountered-an-unsupported-mode-mode-r","errorCode":null,"errorMessage":"Encountered an unsupported mode: {mode!r}","messagePattern":"Encountered an unsupported mode: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/gcp/bigquery_schema_tools.py","lineNumber":116,"sourceCode":"\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\n  Returns:\n    The corresponding Python type hint.\n  \"\"\"\n  effective_types = {**BIG_QUERY_TO_PYTHON_TYPES, **(type_overrides or {})}\n  if mode == 'NULLABLE' or mode is None or mode == '':\n    return Optional[effective_types[field]]\n  elif mode == 'REPEATED':\n    return Sequence[effective_types[field]]\n  elif mode == 'REQUIRED':\n    return effective_types[field]\n  else:\n    raise ValueError(f\"Encountered an unsupported mode: {mode!r}\")\n\n\ndef convert_to_usertype(\n    table_schema, selected_fields=None, type_overrides=None):\n  \"\"\"Convert a BigQuery table schema to a user type.\n\n  Args:\n    table_schema: A BQ schema of type TableSchema\n    selected_fields: if not None, the subset of fields to consider\n    type_overrides: Optional mapping of BigQuery type names (uppercase)\n      to Python types.\n\n  Returns:\n    A ParDo transform that converts dictionaries to the user type.\n  \"\"\"\n  usertype = generate_user_type_from_bq_schema(\n      table_schema, selected_fields, type_overrides)\n  return beam.ParDo(BeamSchemaConversionDoFn(usertype))","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/gcp/bigquery_schema_tools.py#L98-L134","documentation":"bq_field_to_type maps a BigQuery field to a Python type hint based on its mode; only NULLABLE (or None/''), REPEATED, and REQUIRED are handled. Any other mode string (e.g. from an outdated API or hand-built schema) falls through to this unsupported-mode error.","triggerScenarios":"Calling bq_field_to_type(field['type'], field['mode'], overrides) — directly or via convert_to_usertype / generate_user_type_from_bq_schema — with mode values like None, 'NULLABLE ' (trailing space), lowercase 'nullable', or fabricated modes.","commonSituations":"Hand-crafted schema dicts missing the 'mode' key (passing None); schemas exported by tools that use different mode casing; trimming/whitespace issues when copying schema JSON from BigQuery console or docs.","solutions":["Ensure every schema field has mode set to one of 'NULLABLE', 'REQUIRED', or 'REPEATED' (case-sensitive).","Default missing modes to 'NULLABLE' when building the schema dict: field.setdefault('mode', 'NULLABLE').","Normalize/strip mode strings before calling, e.g. field['mode'].strip().upper().","Inspect the schema source (console export, REST response) for unexpected mode values and correct them."],"exampleFix":"# before\nfields = [{'name': 'x', 'type': 'STRING'}]\nconvert_to_usertype({'fields': fields})  # mode is None\n\n# after\nfields = [{'name': 'x', 'type': 'STRING', 'mode': 'NULLABLE'}]\nconvert_to_usertype({'fields': fields})","handlingStrategy":"validation","validationCode":"VALID_MODES = {'NULLABLE', 'REQUIRED', 'REPEATED'}\nfor f in schema['fields']:\n    mode = (f.get('mode') or 'NULLABLE').strip().upper()\n    if mode not in VALID_MODES:\n        raise ValueError(f\"invalid mode {f.get('mode')!r} for field {f['name']!r}\")","typeGuard":"def has_valid_mode(field):\n    return field.get('mode') in ('NULLABLE', 'REQUIRED', 'REPEATED')","tryCatchPattern":"try:\n    usertype = convert_to_usertype(schema)\nexcept ValueError as e:\n    if 'unsupported mode' in str(e):\n        raise SchemaConfigError('fix field mode (NULLABLE/REQUIRED/REPEATED)') from e\n    raise","preventionTips":["Always set mode explicitly on every schema field","Normalize mode casing/whitespace when importing schemas from external tools","Use BigQuery's real API response as schema source instead of hand-typed dicts"],"tags":["bigquery","schema","mode","python"],"backgroundTag":"invalid-enum-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}