apache/beam · error · ValueError

Encountered an unsupported mode: {mode!r}

Error message

Encountered an unsupported mode: {mode!r}

What it means

bq_field_to_type maps a BigQuery field to a Python type hint based on its mode; only NULLABLE (or None/''), REPEATED, and REQUIRED are handled. Any other mode string (e.g. from an outdated API or hand-built schema) falls through to this unsupported-mode error.

Source

Thrown at sdks/python/apache_beam/io/gcp/bigquery_schema_tools.py:116

  Args:
    field: The BigQuery type name (e.g., 'STRING', 'DATE').
    mode: The field mode ('NULLABLE', 'REPEATED', 'REQUIRED').
    type_overrides: Optional mapping of BigQuery type names (uppercase)
      to Python types. These override the default mappings.

  Returns:
    The corresponding Python type hint.
  """
  effective_types = {**BIG_QUERY_TO_PYTHON_TYPES, **(type_overrides or {})}
  if mode == 'NULLABLE' or mode is None or mode == '':
    return Optional[effective_types[field]]
  elif mode == 'REPEATED':
    return Sequence[effective_types[field]]
  elif mode == 'REQUIRED':
    return effective_types[field]
  else:
    raise ValueError(f"Encountered an unsupported mode: {mode!r}")


def convert_to_usertype(
    table_schema, selected_fields=None, type_overrides=None):
  """Convert a BigQuery table schema to a user type.

  Args:
    table_schema: A BQ schema of type TableSchema
    selected_fields: if not None, the subset of fields to consider
    type_overrides: Optional mapping of BigQuery type names (uppercase)
      to Python types.

  Returns:
    A ParDo transform that converts dictionaries to the user type.
  """
  usertype = generate_user_type_from_bq_schema(
      table_schema, selected_fields, type_overrides)
  return beam.ParDo(BeamSchemaConversionDoFn(usertype))

View on GitHub (pinned to 12126d8942)

Solutions

  1. Ensure every schema field has mode set to one of 'NULLABLE', 'REQUIRED', or 'REPEATED' (case-sensitive).
  2. Default missing modes to 'NULLABLE' when building the schema dict: field.setdefault('mode', 'NULLABLE').
  3. Normalize/strip mode strings before calling, e.g. field['mode'].strip().upper().
  4. Inspect the schema source (console export, REST response) for unexpected mode values and correct them.

Example fix

# before
fields = [{'name': 'x', 'type': 'STRING'}]
convert_to_usertype({'fields': fields})  # mode is None

# after
fields = [{'name': 'x', 'type': 'STRING', 'mode': 'NULLABLE'}]
convert_to_usertype({'fields': fields})
Defensive patterns

Strategy: validation

Validate before calling

VALID_MODES = {'NULLABLE', 'REQUIRED', 'REPEATED'}
for f in schema['fields']:
    mode = (f.get('mode') or 'NULLABLE').strip().upper()
    if mode not in VALID_MODES:
        raise ValueError(f"invalid mode {f.get('mode')!r} for field {f['name']!r}")

Type guard

def has_valid_mode(field):
    return field.get('mode') in ('NULLABLE', 'REQUIRED', 'REPEATED')

Try / catch

try:
    usertype = convert_to_usertype(schema)
except ValueError as e:
    if 'unsupported mode' in str(e):
        raise SchemaConfigError('fix field mode (NULLABLE/REQUIRED/REPEATED)') from e
    raise

Prevention

When it happens

Trigger: Calling bq_field_to_type(field['type'], field['mode'], overrides) — directly or via convert_to_usertype / generate_user_type_from_bq_schema — with mode values like None, 'NULLABLE ' (trailing space), lowercase 'nullable', or fabricated modes.

Common situations: Hand-crafted schema dicts missing the 'mode' key (passing None); schemas exported by tools that use different mode casing; trimming/whitespace issues when copying schema JSON from BigQuery console or docs.

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/25732df982e5cfd6. Report an issue: GitHub.