{"record":{"id":"8330c32f049183f1","repo":"apache/beam","slug":"unknown-bigquery-field-mode","errorCode":null,"errorMessage":"Unknown BigQuery field mode: {}","messagePattern":"Unknown BigQuery field mode: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/gcp/bigquery_avro_tools.py","lineNumber":134,"sourceCode":"\n  if avro_type == \"record\":\n    element_type = get_record_schema_from_dict_table_schema(\n        table_field[\"name\"],\n        table_field,\n        namespace=\".\".join((namespace, table_field[\"name\"])))\n  else:\n    element_type = avro_type\n\n  field_mode = table_field.get(\"mode\", \"NULLABLE\")\n\n  if field_mode in (None, \"NULLABLE\"):\n    field_type = [\"null\", element_type]\n  elif field_mode == \"REQUIRED\":\n    field_type = element_type\n  elif field_mode == \"REPEATED\":\n    field_type = {\"type\": \"array\", \"items\": element_type}\n  else:\n    raise ValueError(\"Unknown BigQuery field mode: {}\".format(field_mode))\n\n  avro_field = {\"type\": field_type, \"name\": table_field[\"name\"]}\n\n  doc = table_field.get(\"description\")\n  if doc:\n    avro_field[\"doc\"] = doc\n\n  return avro_field\n","sourceCodeStart":116,"sourceCodeEnd":143,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/gcp/bigquery_avro_tools.py#L116-L143","documentation":"table_field_to_avro_field converts a BigQuery table schema field into an Avro field schema. BigQuery field modes must be NULLABLE, REQUIRED, or REPEATED; any other mode string cannot be mapped to an Avro type, so the function raises ValueError. This indicates malformed or unexpected schema metadata rather than a data problem.","triggerScenarios":"Calling get_record_schema_from_dict_table_schema with a dict-based BigQuery table schema whose field has a 'mode' value that is not exactly 'NULLABLE', 'REQUIRED', or 'REPEATED' (e.g. 'Optional', lowercase 'nullable', empty string, or None for a field where the nested element_type path was taken).","commonSituations":"Hand-constructed or third-party-generated table schemas with missing or misspelled 'mode'; schemas fetched with a client that returns 'REPEATED' differently; typos when writing dict table schemas by hand.","solutions":["Inspect the offending table_field['mode'] value and set it to one of 'NULLABLE', 'REQUIRED', or 'REPEATED' (exact case).","If mode is absent, add an explicit mode to each field in the dict table schema (BigQuery defaults to NULLABLE).","Fetch the schema via a supported BigQuery client/API (e.g. client.get_table(table).to_api_repr()) instead of hand-writing it.","If constructing programmatically, validate modes against {'NULLABLE','REQUIRED','REPEATED'} before passing the schema in."],"exampleFix":"# before\nfield = {\"name\": \"ids\", \"type\": \"INTEGER\", \"mode\": \"repeated\"}\n# after\nfield = {\"name\": \"ids\", \"type\": \"INTEGER\", \"mode\": \"REPEATED\"}","handlingStrategy":"validation","validationCode":"VALID_MODES = {\"NULLABLE\", \"REQUIRED\", \"REPEATED\"}\nassert all(f.get(\"mode\") in VALID_MODES for f in table_schema[\"fields\"]), \\\n    \"table schema field mode must be NULLABLE, REQUIRED, or REPEATED\"","typeGuard":"def has_valid_modes(schema: dict) -> bool:\n    return all(f.get(\"mode\") in (\"NULLABLE\", \"REQUIRED\", \"REPEATED\") for f in schema.get(\"fields\", []))","tryCatchPattern":"try:\n    avro_schema = get_record_schema_from_dict_table_table(table_schema)\nexcept ValueError as e:\n    log.error(\"invalid BigQuery field mode: %s\", e)\n    raise","preventionTips":["Use client.get_table(...).to_api_repr() to obtain schemas instead of hand-writing them","Validate mode strings against the exact uppercase enum before conversion","Never omit 'mode' when constructing dict table schemas manually"],"tags":["python","apache-beam","bigquery","avro","schema"],"backgroundTag":"schema-validation-failed","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"}