{"record":{"id":"ad7298ea8b3ccdfe","repo":"apache/beam","slug":"schema-update-options-must-be-a-list-received-s","errorCode":null,"errorMessage":"schema_update_options must be a list. Received %s.","messagePattern":"schema_update_options must be a list\\. Received (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/gcp/bigquery.py","lineNumber":624,"sourceCode":"        BigQueryDisposition.WRITE_APPEND,\n        BigQueryDisposition.WRITE_EMPTY)\n    if disposition not in values:\n      raise ValueError(\n          'Invalid write disposition %s. Expecting %s' % (disposition, values))\n    return disposition\n\n\nclass BigQuerySchemaUpdateOption(str, Enum):\n  \"\"\"Enum holding standard strings used for schema update options.\"\"\"\n\n  ALLOW_FIELD_ADDITION = 'ALLOW_FIELD_ADDITION'\n  ALLOW_FIELD_RELAXATION = 'ALLOW_FIELD_RELAXATION'\n\n  @staticmethod\n  def validate(options):\n    if options is None:\n      return None\n    if not isinstance(options, list):\n      raise ValueError(\n          'schema_update_options must be a list. Received %s.' %\n          type(options).__name__)\n    values = tuple(option.value for option in BigQuerySchemaUpdateOption)\n    validated_options = []\n    for option in options:\n      try:\n        validated_options.append(BigQuerySchemaUpdateOption(option).value)\n      except ValueError:\n        raise ValueError(\n            'Invalid schema update option %s. Expecting %s' %\n            (option, values)) from None\n    return validated_options\n\n\nclass BigQueryQueryPriority(object):\n  \"\"\"Class holding standard strings used for query priority.\"\"\"\n","sourceCodeStart":606,"sourceCodeEnd":642,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/gcp/bigquery.py#L606-L642","documentation":"BigQuerySchemaUpdateOption.validate is a type guard on the schema_update_options argument: it only accepts a list of option strings (or None). Any other type (e.g. a single string or tuple) is rejected before the options reach the BigQuery job configuration.","triggerScenarios":"Passing schema_update_options='ALLOW_FIELD_ADDITION' (a bare string) or a tuple/set instead of a list to WriteToBigQuery.","commonSituations":"Passing a single option as a plain string instead of a one-element list, since a string is iterable but not a list.","solutions":["Wrap the option in a list: schema_update_options=['ALLOW_FIELD_ADDITION']","Convert tuples/sets: list(options)","Pass None explicitly if no options are needed"],"exampleFix":"// before\nWriteToBigQuery(..., schema_update_options='ALLOW_FIELD_RELAXATION')\n// after\nWriteToBigQuery(..., schema_update_options=['ALLOW_FIELD_RELAXATION'])","handlingStrategy":"type-guard","validationCode":"if schema_update_options is not None and not isinstance(schema_update_options, list):\n    schema_update_options = list(schema_update_options)","typeGuard":"def is_options_list(x):\n    return x is None or (isinstance(x, list) and all(isinstance(o, str) for o in x))","tryCatchPattern":"try:\n    BigQuerySchemaUpdateOption.validate(options)\nexcept ValueError as e:\n    if 'must be a list' in str(e):\n        options = [options] if isinstance(options, str) else list(options)\n    else:\n        raise","preventionTips":["Always pass lists for list-typed options","Convert single string options to [option] in helpers","Validate pipeline options right after parsing"],"tags":["python","apache-beam","bigquery","argument-type"],"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"}