apache/beam · error · ValueError

Invalid create disposition %s. Expecting %s

Error message

Invalid create disposition %s. Expecting %s

What it means

BigQueryDisposition.validate_create checks that a create disposition is one of CREATE_NEVER or CREATE_IF_NEEDED; any other string raises ValueError. This validates the static configuration of BigQuery sinks/loads.

Source

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

    return bigquery.TableRow(
        f=[bigquery.TableCell(v=to_json_value(e)) for e in od.values()])


class BigQueryDisposition(object):
  """Class holding standard strings used for create and write dispositions."""

  CREATE_NEVER = 'CREATE_NEVER'
  CREATE_IF_NEEDED = 'CREATE_IF_NEEDED'
  WRITE_TRUNCATE = 'WRITE_TRUNCATE'
  WRITE_APPEND = 'WRITE_APPEND'
  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."""

View on GitHub (pinned to 12126d8942)

Solutions

1. Use the enum constants: BigQueryDisposition.CREATE_IF_NEEDED or CREATE_NEVER
2. Fix the typo/casing of the disposition string
3. Validate user-provided config through validate_create before constructing the sink

Example fix

// before
WriteToBigQuery(..., create_disposition='create_if_needed')
// after
from apache_beam.io.gcp.bigquery import BigQueryDisposition
WriteToBigQuery(..., create_disposition=BigQueryDisposition.CREATE_IF_NEEDED)

from apache_beam.io.gcp.bigquery import BigQueryDisposition
assert create_disposition in (BigQueryDisposition.CREATE_IF_NEEDED, BigQueryDisposition.CREATE_NEVER)

def is_valid_create_disposition(d):
    return d in ('CREATE_IF_NEEDED', 'CREATE_NEVER')

try:
    BigQueryDisposition.validate_create(disposition)
except ValueError as e:
    logging.error('Bad create disposition %r, defaulting', disposition)
    disposition = BigQueryDisposition.CREATE_IF_NEEDED

When it happens

Trigger: Passing create_disposition with a typo or unsupported value (e.g. 'CREATE_IF_NEDED', 'create_if_needed', or empty string) to WriteToBigQuery or BigQuery batch load configuration.

Common situations: Hand-typed disposition strings copied from SQL/other SDKs with different casing or naming; programmatic config assembled from user input.

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 write 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/501d332a6e4b7741. Report an issue: GitHub.