What causes "Cannot get a type descriptor for %s." in apache/beam?

Convert the value to a supported primitive before encoding: `float(np_value)`, `str(obj)`, or `json.dumps(obj)` as a string.

apache/beam · error · TypeError

Cannot get a type descriptor for %s.

Error message

Cannot get a type descriptor for %s.

What it means

get_typed_value_descriptor converts a Python scalar into a schema.org-typed descriptor (Boolean/Integer/Float) for Beam's internal JSON encoding. If the object is not None, str, bytes, bool, int, or float it raises TypeError 'Cannot get a type descriptor for %s' with repr of the offending object.

Source

Thrown at sdks/python/apache_beam/internal/gcp/json_value.py:61

  Returns:
    A dictionary containing the keys ``@type`` and ``value`` with the value for
    the ``@type`` of appropriate type.

  Raises:
    TypeError: if the Python object has a type that is not
      supported.
  """
  if isinstance(obj, (bytes, str)):
    type_name = 'Text'
  elif isinstance(obj, bool):
    type_name = 'Boolean'
  elif isinstance(obj, int):
    type_name = 'Integer'
  elif isinstance(obj, float):
    type_name = 'Float'
  else:
    raise TypeError('Cannot get a type descriptor for %s.' % repr(obj))
  return {'@type': 'http://schema.org/%s' % type_name, 'value': obj}


def to_json_value(obj, with_type=False):
  """For internal use only; no backwards-compatibility guarantees.

  Converts Python objects into extra_types.JsonValue objects.

  Args:
    obj: Python object to be converted. Can be :data:`None`.
    with_type: If true then the basic types (``bytes``, ``unicode``, ``int``,
      ``float``, ``bool``) will be wrapped in ``@type:value`` dictionaries.
      Otherwise the straight value is encoded into a ``JsonValue``.

  Returns:
    A ``JsonValue`` object using ``JsonValue``, ``JsonArray`` and ``JsonObject``
    types for the corresponding values, lists, or dictionaries.

View on GitHub (pinned to 12126d8942)

Solutions

Convert the value to a supported primitive before encoding: `float(np_value)`, `str(obj)`, or `json.dumps(obj)` as a string.
Only pass with_type=True for scalar values; encode composites as plain JSON structures.
Check type with isinstance against (bool, int, float, str, bytes) before calling.

Example fix

// before
to_json_value(np.float32(1.5), with_type=True)  # TypeError
// after
to_json_value(float(np.float32(1.5)), with_type=True)

Defensive patterns

Strategy: validation

Validate before calling

def encodable_with_type(v) -> bool:
    if v is None: return True
    return isinstance(v, (str, bytes, bool, int, float))

Type guard

def is_schema_typed_scalar(v) -> bool:
    return v is None or isinstance(v, (str, bytes, bool, int, float))

Try / catch

try:
    return to_json_value(v, with_type=True)
except TypeError as e:
    if 'type descriptor' in str(e):
        return to_json_value(repr(v))  # fall back to string encoding
    raise

Prevention

Convert numpy scalars to native Python types before encoding.
Only use with_type=True for scalar values.
Coerce datetime/Decimal/custom objects to str or primitives first.

When it happens

Trigger: Calling to_json_value(obj, with_type=True) (which delegates to get_typed_value_descriptor) with an unsupported type such as a list, dict, datetime, Decimal, or custom object; passing a numpy scalar (numpy.float32 is not a Python float and fails isinstance checks).

Common situations: Encoding pipeline parameters with composite values while requesting typed output; numpy numeric types that fail isinstance(float); passing enums or dataclasses instead of primitives.

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/1f3ab3304646d531. Report an issue: GitHub.