apache/beam · error · ValueError

Only atomic_type and array_type option values are currently…

Error message

Only atomic_type and array_type option values are currently supported in Python. Got {value!r}, which maps to fieldtype {typing_proto!r}.

What it means

`value_to_runner_api` can only serialize Python option values that map to atomic_type (scalars) or array_type (lists). Anything else — dicts, rows, nested structures — has no supported proto mapping and raises this ValueError.

Solutions

1. Serialize the value to a supported type yourself (e.g. JSON string or flat list) before setting the option
2. Use primitives (str/int/float/bool/bytes) or flat lists of primitives
3. Restructure the data so it doesn't need to travel as an option

Example fix

// before
row.RowTypeConstraint option value: Option('conf', value={'k': 1})
// after
import json; Option('conf', value=json.dumps({'k': 1}))

if isinstance(value, (dict, tuple)) or hasattr(value, '_asdict'):
  value = json.dumps(value)  # pre-serialize before schema conversion

def is_option_supported(v) -> bool:
  return isinstance(v, (str, int, float, bool, bytes, list))

try:
  proto = converter.value_to_runner_api(tp, value)
except ValueError:
  proto = converter.value_to_runner_api(tp, json.dumps(value, default=str))

When it happens

Trigger: Calling `value_to_runner_api` (via `option_to_runner_api` or a schema option with e.g. a dict or namedtuple value) where the inferred FieldType is not atomic or array.

Common situations: Setting a pipeline option or schema option to a dict/struct in Python; passing rich objects as options in cross-language pipelines.

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

• Attempted to encode null for non-nullable field
• Encountered option with unsupported type. Only atomic_type…
• A schema is required to write non-schema'd data.
• All dicts in batch must have the same keys. extra keys
• An explicit schema is required to write non-schema'd…

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

Appendix: source

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

          "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:
      raise ValueError(
          "Only atomic_type and array_type option values are currently "
          f"supported in Python. Got {value!r}, which maps to fieldtype "
          f"{typing_proto!r}.")

  def option_from_runner_api(
      self, option_proto: schema_pb2.Option) -> Tuple[str, Any]:
    if not option_proto.HasField('type'):
      return option_proto.name, None

    value = self.value_from_runner_api(option_proto.type, option_proto.value)
    return option_proto.name, value

  def option_to_runner_api(self, option: Tuple[str, Any]) -> schema_pb2.Option:
    name, value = option

    if value is None:
      # a value of None indicates the option is just a flag.
      # Don't set type, value

View on GitHub (pinned to 12126d8942)