apache/beam · error · ValueError

Unrecognized atomic_type

Error message

Unrecognized atomic_type {atomic_type} when encoding value {value}

What it means

`atomic_value_to_runner_api` maps a Python scalar to its AtomicTypeValue proto based on the resolved atomic_type; only STRING, INT, DOUBLE, BOOLEAN, BYTES are handled. Note the message lacks f-strings, so the placeholders print literally. Any other field type produces this ValueError.

Solutions

Convert the value to a supported Python scalar (int, float, str, bool, bytes) before setting it
Use an appropriate logical/annotation type or restructure the field so it maps to a supported atomic type
Upgrade Beam if a newer version supports your value's type

Example fix

// before
option = Option('ts', value=np.datetime64('2024-01-01'))
// after
option = Option('ts', value='2024-01-01')  # encode as string

Defensive patterns

Strategy: validation

Validate before calling

if not isinstance(value, (str, int, float, bool, bytes)):
  raise TypeError('option value must be a supported atomic scalar')

Type guard

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

Try / catch

try:
  opt = option_to_runner_api(opt)
except ValueError:
  opt = option_to_runner_api(Option(opt.name, value=str(opt.value)))

Prevention

Coerce numpy scalars and datetimes to native Python types
Only use str/int/float/bool/bytes for schema options

When it happens

Trigger: Calling `value_to_runner_api` with a value whose inferred atomic_type isn't one of the five supported kinds, e.g. an unsupported scalar like a complex number or numpy scalar being converted to a schema option/field.

Common situations: Passing numpy scalars (np.int32) or datetimes directly as option values; converting schemas with exotic field types between SDKs.

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/2804ed195b48acc2. Report an issue: GitHub.

Appendix: source

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

      atomic_value = schema_pb2.AtomicTypeValue(byte=value)
    elif atomic_type == schema_pb2.INT16:
      atomic_value = schema_pb2.AtomicTypeValue(int16=value)
    elif atomic_type == schema_pb2.INT32:
      atomic_value = schema_pb2.AtomicTypeValue(int32=value)
    elif atomic_type == schema_pb2.INT64:
      atomic_value = schema_pb2.AtomicTypeValue(int64=value)
    elif atomic_type == schema_pb2.FLOAT:
      atomic_value = schema_pb2.AtomicTypeValue(float=value)
    elif atomic_type == schema_pb2.DOUBLE:
      atomic_value = schema_pb2.AtomicTypeValue(double=value)
    elif atomic_type == schema_pb2.STRING:
      atomic_value = schema_pb2.AtomicTypeValue(string=value)
    elif atomic_type == schema_pb2.BOOLEAN:
      atomic_value = schema_pb2.AtomicTypeValue(boolean=value)
    elif atomic_type == schema_pb2.BYTES:
      atomic_value = schema_pb2.AtomicTypeValue(bytes=value)
    else:
      raise ValueError(
          "Unrecognized atomic_type {atomic_type} when encoding value {value}")

    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
      ]

View on GitHub (pinned to 12126d8942)