apache/beam · error · ValueError

Invalid write disposition %s. Expecting %s

Error message

Invalid write disposition %s. Expecting %s

What it means

BigQueryDisposition.validate_write rejects a write disposition string that is not one of WRITE_TRUNCATE, WRITE_APPEND, or WRITE_EMPTY. The offending value is the 'disposition' argument passed to the BigQuery sink/Source.

Source

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

  WRITE_EMPTY = 'WRITE_EMPTY'

  @staticmethod
  def validate_create(disposition):
    values = (
        BigQueryDisposition.CREATE_NEVER, BigQueryDisposition.CREATE_IF_NEEDED)
    if disposition not in values:
      raise ValueError(
          'Invalid create disposition %s. Expecting %s' % (disposition, values))
    return disposition

  @staticmethod
  def validate_write(disposition):
    values = (
        BigQueryDisposition.WRITE_TRUNCATE,
        BigQueryDisposition.WRITE_APPEND,
        BigQueryDisposition.WRITE_EMPTY)
    if disposition not in values:
      raise ValueError(
          'Invalid write disposition %s. Expecting %s' % (disposition, values))
    return disposition


class BigQuerySchemaUpdateOption(str, Enum):
  """Enum holding standard strings used for schema update options."""

  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__)

View on GitHub (pinned to 12126d8942)

Solutions

1. Use BigQueryDisposition.WRITE_APPEND / WRITE_TRUNCATE / WRITE_EMPTY constants
2. Correct the disposition string spelling and casing
3. Pre-validate with BigQueryDisposition.validate_write(value)

Example fix

// before
WriteToBigQuery(..., write_disposition='WRITE_APPEND ')  # trailing space
// after
WriteToBigQuery(..., write_disposition=BigQueryDisposition.WRITE_APPEND)

from apache_beam.io.gcp.bigquery import BigQueryDisposition
assert write_disposition in (BigQueryDisposition.WRITE_TRUNCATE, BigQueryDisposition.WRITE_APPEND, BigQueryDisposition.WRITE_EMPTY)

def is_valid_write_disposition(d):
    return d in ('WRITE_TRUNCATE', 'WRITE_APPEND', 'WRITE_EMPTY')

try:
    BigQueryDisposition.validate_write(disposition)
except ValueError as e:
    logging.error('Bad write disposition %r, defaulting', disposition)
    disposition = BigQueryDisposition.WRITE_APPEND

When it happens

Trigger: Passing write_disposition with an invalid value (typo, wrong case, e.g. 'WRITE_TRUNCATED' or 'append') to WriteToBigQuery or BigQuery load configuration.

Common situations: Copy-pasting dispositions from other BigQuery client libraries with different naming; typos in YAML/config-driven pipelines.

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 schema update option %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/d30b3f8721f160c9. Report an issue: GitHub.