apache/beam · error · ValueError

The method to read from BigQuery must be either EXPORT or…

Error message

The method to read from BigQuery must be either EXPORT or DIRECT_READ.

What it means

ReadFromBigQuery.expand dispatches on self.method and only supports ReadFromBigQuery.Method.EXPORT and Method.DIRECT_READ. A ValueError is raised (bigquery.py:3100) when method holds any other value, meaning the transform has no read implementation to run.

Solutions

Set method=ReadFromBigQuery.Method.EXPORT or ReadFromBigQuery.Method.DIRECT_READ
Do not pass a raw string; import the Method enum from ReadFromBigQuery
Print ReadFromBigQuery.Method.__members__ to confirm valid values in your Beam version

Example fix

// before
ReadFromBigQuery(table=t, method='EXPORT')
// after
ReadFromBigQuery(table=t, method=ReadFromBigQuery.Method.EXPORT)

Defensive patterns

Strategy: validation

Validate before calling

assert method in (ReadFromBigQuery.Method.EXPORT, ReadFromBigQuery.Method.DIRECT_READ), method

Type guard

def is_valid_method(m):
    return m in (ReadFromBigQuery.Method.EXPORT, ReadFromBigQuery.Method.DIRECT_READ)

Try / catch

try:
    result = pcoll | ReadFromBigQuery(method=method, ...)
except ValueError as e:
    if 'EXPORT or DIRECT_READ' in str(e):
        method = ReadFromBigQuery.Method.EXPORT

Prevention

Always use the ReadFromBigQuery.Method enum, never raw strings
Pin your Beam version and check enum members after upgrades
Centralize transform construction to validate options once

When it happens

Trigger: Passing method='export' (wrong case/string instead of the enum), method=None explicitly, a custom string, or an enum from a differently-versioned Beam where the value is not one of the two supported members.

Common situations: Treating method as a free-form string instead of ReadFromBigQuery.Method; typos like Method.Export; constructing the transform programmatically with a variable that is None; pickled configs from older Beam versions.

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

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

Appendix: source

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

            "provide query_output_schema so the output schema can be "
            "determined without reading an existing table. The schema should "
            "be a BigQuery schema dict, e.g. "
            "{'fields': [{'name': 'col', 'type': 'STRING', 'mode': 'NULLABLE'}"
            ", ...]}, or a TableSchema object.")

    self.gcs_location = gcs_location
    self.bigquery_dataset_labels = {
        'type': 'bq_direct_read_' + str(uuid.uuid4())[0:10]
    }

  def expand(self, pcoll):
    if self.method == ReadFromBigQuery.Method.EXPORT:
      output_pcollection = self._expand_export(pcoll)
    elif self.method == ReadFromBigQuery.Method.DIRECT_READ:
      output_pcollection = self._expand_direct_read(pcoll)

    else:
      raise ValueError(
          'The method to read from BigQuery must be either EXPORT '
          'or DIRECT_READ.')
    return self._expand_output_type(output_pcollection)

  def _expand_output_type(self, output_pcollection):
    if self.output_type == 'PYTHON_DICT' or self.output_type is None:
      return output_pcollection
    elif self.output_type == 'BEAM_ROW':
      if self._kwargs.get('query', None) is not None:
        user_schema = bigquery_tools.get_dict_table_schema(
            self.query_output_schema)
        return output_pcollection | bigquery_schema_tools.convert_to_usertype(
            user_schema, self._kwargs.get('selected_fields', None))
      table_details = bigquery_tools.parse_table_reference(
          table=self._kwargs.get("table", None),
          dataset=self._kwargs.get("dataset", None),
          project=self._kwargs.get("project", None))
      if isinstance(self._kwargs['table'], ValueProvider):

View on GitHub (pinned to 12126d8942)