apache/beam · error · ValueError

Unrecognized atomic_type

Error message

Unrecognized atomic_type ({atomic_type}) when decoding value {atomic_value!r}

What it means

When decoding a schema FieldValue from the runner's proto form, `atomic_value_from_runner_api` only handles STRING, INT, DOUBLE, BOOLEAN, BYTES atomic types. Any other atomic_type in the proto (e.g. new enum values added in a newer Beam protocol version) has no Python mapping and triggers this ValueError.

Solutions

1. Upgrade apache-beam to a version whose schema_pb2 knows the atomic type
2. Inspect the failing proto's atomic_type value and confirm it's a supported one (STRING/INT/DOUBLE/BOOLEAN/BYTES)
3. Align runner and SDK versions so the schema protos match

supported = {schema_pb2.STRING, schema_pb2.INT, schema_pb2.DOUBLE, schema_pb2.BOOLEAN, schema_pb2.BYTES}
assert atomic_type in supported, f'unsupported atomic_type {atomic_type}'

try:
  value = converter.value_from_runner_api(tp, proto)
except ValueError as e:
  log.error('runner proto uses unsupported atomic type; upgrade SDK'); raise

When it happens

Trigger: Calling `value_from_runner_api` (or materializing a typed schema) with an AtomicTypeValue proto whose atomic_type enum is not one of the recognized values — commonly protos produced by a newer runner/SDK than the local one.

Common situations: Cross-language pipelines where another SDK writes a schema with an atomic type the Python SDK version doesn't know; Beam version mismatch between runner and SDK.

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

• Encountered option with unsupported type. Only atomic_type…
• Failed to decode schema due to an issue with Field proto
• Unrecognized atomic_type
• Unrecognized type_info
• Unrecognized type_info

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

Appendix: source

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

      value = np.int8(atomic_value.byte)
    elif atomic_type == schema_pb2.INT16:
      value = np.int16(atomic_value.int16)
    elif atomic_type == schema_pb2.INT32:
      value = np.int32(atomic_value.int32)
    elif atomic_type == schema_pb2.INT64:
      value = np.int64(atomic_value.int64)
    elif atomic_type == schema_pb2.FLOAT:
      value = np.float32(atomic_value.float)
    elif atomic_type == schema_pb2.DOUBLE:
      value = np.float64(atomic_value.double)
    elif atomic_type == schema_pb2.STRING:
      value = atomic_value.string
    elif atomic_type == schema_pb2.BOOLEAN:
      value = atomic_value.boolean
    elif atomic_type == schema_pb2.BYTES:
      value = atomic_value.bytes
    else:
      raise ValueError(
          f"Unrecognized atomic_type ({atomic_type}) "
          f"when decoding value {atomic_value!r}")

    return value

  def atomic_value_to_runner_api(
      self, atomic_type: schema_pb2.AtomicType,
      value) -> schema_pb2.AtomicTypeValue:
    if atomic_type == schema_pb2.BYTE:
      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)

View on GitHub (pinned to 12126d8942)