apache/beam · error · ValueError

Encountered option with unsupported type. Only atomic_type…

Error message

Encountered option with unsupported type. Only atomic_type and array_type options are supported: {type_proto}

What it means

`value_from_runner_api` decodes option values from proto and only supports atomic_type and array_type FieldTypes. If the proto says the option's type is something else (e.g. map_type, row_type, logical_type), it raises this ValueError because there is no Python value representation implemented for it.

Solutions

Restructure the option to be a plain atomic or array value (flatten maps/rows into primitives)
Handle the option in the producing SDK differently or drop it before crossing into Python
Upgrade apache-beam in case support was added later

Example fix

// before
Option('params', value={'a': 1})  # map_type not supported when decoded
// after
Option('params', value=['a=1'])  # array of strings

Defensive patterns

Strategy: validation

Validate before calling

info = type_proto.WhichOneof('type_info')
if info not in ('atomic_type', 'array_type'):
  raise ValueError(f'option type {info} not supported in Python')

Try / catch

try:
  name, val = converter.option_from_runner_api(opt)
except ValueError:
  name, val = opt.name, None  # fallback: skip structured options

Prevention

Keep option values flat: scalars or arrays only
Avoid structured options in cross-language pipelines consumed by Python

When it happens

Trigger: Receiving/decoding an Option proto whose type_info is map_type, row_type, iterable_type, etc. — typically an option set by a Java/Go pipeline or newer SDK with a non-atomic, non-array option value.

Common situations: Cross-language transforms that attach structured options; pipelines built in another SDK decoded by Python.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/typehints/schemas.py:500

    return atomic_value

  def value_from_runner_api(
      self,
      type_proto: schema_pb2.FieldType,
      value_proto: schema_pb2.FieldValue):
    type_info = type_proto.WhichOneof("type_info")
    if type_info == "atomic_type":
      return self.atomic_value_from_runner_api(
          type_proto.atomic_type, value_proto.atomic_value)
    elif type_info == "array_type":
      element_type = type_proto.array_type.element_type
      return [
          self.value_from_runner_api(element_type, element)
          for element in value_proto.array_value.element
      ]
    else:
      raise ValueError(
          "Encountered option with unsupported type. Only atomic_type and "
          f"array_type options are supported: {type_proto}")

  def value_to_runner_api(self, typing_proto: schema_pb2.FieldType, value):
    type_info = typing_proto.WhichOneof("type_info")
    if type_info == "atomic_type":
      return schema_pb2.FieldValue(
          atomic_value=self.atomic_value_to_runner_api(
              typing_proto.atomic_type, value))
    elif type_info == "array_type":
      element_type = typing_proto.array_type.element_type
      return schema_pb2.FieldValue(
          array_value=schema_pb2.ArrayTypeValue(
              element=[
                  self.value_to_runner_api(element_type, element)
                  for element in value
              ]))
    else:

View on GitHub (pinned to 12126d8942)