apache/beam · error · ValueError

Invalid schema update option %s. Expecting %s

Error message

Invalid schema update option %s. Expecting %s

What it means

Each entry in schema_update_options must be a valid BigQuerySchemaUpdateOption (ALLOW_FIELD_ADDITION or ALLOW_FIELD_RELAXATION); an unrecognized option string raises ValueError listing the valid values.

Source

Thrown at sdks/python/apache_beam/io/gcp/bigquery.py:634

  ALLOW_FIELD_ADDITION = 'ALLOW_FIELD_ADDITION'
  ALLOW_FIELD_RELAXATION = 'ALLOW_FIELD_RELAXATION'

  @staticmethod
  def validate(options):
    if options is None:
      return None
    if not isinstance(options, list):
      raise ValueError(
          'schema_update_options must be a list. Received %s.' %
          type(options).__name__)
    values = tuple(option.value for option in BigQuerySchemaUpdateOption)
    validated_options = []
    for option in options:
      try:
        validated_options.append(BigQuerySchemaUpdateOption(option).value)
      except ValueError:
        raise ValueError(
            'Invalid schema update option %s. Expecting %s' %
            (option, values)) from None
    return validated_options


class BigQueryQueryPriority(object):
  """Class holding standard strings used for query priority."""

  INTERACTIVE = 'INTERACTIVE'
  BATCH = 'BATCH'


# -----------------------------------------------------------------------------
# BigQuerySource, BigQuerySink.


@deprecated(since='2.25.0', current="ReadFromBigQuery")
def BigQuerySource(

View on GitHub (pinned to 12126d8942)

Solutions

1. Use BigQuerySchemaUpdateOption.ALLOW_FIELD_ADDITION or ALLOW_FIELD_RELAXATION values exactly
2. Fix spelling/casing of the option string
3. Pre-validate with BigQuerySchemaUpdateOption.validate(options) before constructing the sink

Example fix

// before
WriteToBigQuery(..., schema_update_options=['ALLOW_FIELD_ADDITIONS'])
// after
WriteToBigQuery(..., schema_update_options=['ALLOW_FIELD_ADDITION'])

from apache_beam.io.gcp.bigquery import BigQuerySchemaUpdateOption
valid = {o.value for o in BigQuerySchemaUpdateOption}
assert all(o in valid for o in (schema_update_options or [])), f'options must be in {valid}'

def is_valid_schema_update_option(o):
    try:
        BigQuerySchemaUpdateOption(o)
        return True
    except ValueError:
        return False

try:
    BigQuerySchemaUpdateOption.validate(options)
except ValueError as e:
    if 'Invalid schema update option' in str(e):
        options = [o for o in options if is_valid_schema_update_option(o)]
    else:
        raise

When it happens

Trigger: Passing an option with wrong spelling/case such as 'ALLOW_FIELD_ADDITIONS' or 'FIELD_RELAXATION' inside the schema_update_options list.

Common situations: Typos, outdated option names from older Beam versions, or options invented to match other BigQuery client libraries.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid create disposition %s. Expecting %s
• Invalid write disposition %s. Expecting %s
• change_function must be 'CHANGES' or 'APPENDS', got '{change
• poll_interval_sec must be >= 15, got {poll_interval_sec}
• buffer_sec must be >= 0, got {buffer_sec}

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/35d2c28ca3da618c. Report an issue: GitHub.