apache/beam · error · RuntimeError

bad type

Error message

bad type: %s

What it means

check_constraint raises RuntimeError('bad type: %s') when the type_constraint argument is neither a TypeConstraint, None, nor a Python type (class). This is an internal argument-validation guard: Beam cannot know how to check an object against something that isn't a recognizable type specification.

Solutions

1. Ensure the constraint passed is a class (int, str), a beam TypeConstraint, or None.
2. Convert typing-module generics to Beam hints (or vice versa) compatible with your Beam version; upgrade Beam if typing interop is the issue.
3. Print type(type_constraint) and its __module__ to see what leaked into the API.
4. Wrap custom hint classes in TypeConstraint subclasses so check_constraint can dispatch them.

Example fix

# before
check_constraint('int', value)  # string, not a type
# after
check_constraint(int, value)

from apache_beam.typehints import TypeConstraint
def is_checkable_constraint(c):
    return isinstance(c, TypeConstraint) or c is None or isinstance(c, type)

def is_class(x):
    return isinstance(x, type)

try:
    check_constraint(tc, value)
except RuntimeError as e:
    if str(e).startswith('bad type:'):
        logger.error('invalid constraint object: %r', tc)
    raise

When it happens

Trigger: Calling check_constraint (directly or via type_check paths like _check_instance_type) with an invalid constraint such as an instance, a string like 'int', or a typing generic object not understood by Beam (older Python typing interop gaps).

Common situations: Hand-written type hints passed into Beam internals; mixing typing.List[int] objects into Beam's own constraint API on versions where interop is incomplete; custom hint objects that subclass neither TypeConstraint nor type.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• A transform with label
• An Option type-hint only accepts a single type parameter.
• batch type must be List[T] for element type T
• batch type must be np.ndarray or…
• Cannot access the output of an error handler until it has…

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

Appendix: source

Thrown at sdks/python/apache_beam/typehints/typehints.py:431

  Args:
    type_constraint: An instance of a TypeConstraint or a built-in Python type.
    object_instance: An object instance.

  Raises:
    SimpleTypeHintError: If 'type_constraint' is a one of the allowed primitive
      Python types and 'object_instance' isn't an instance of this type.
    CompositeTypeHintError: If 'type_constraint' is a TypeConstraint object and
      'object_instance' does not satisfy its constraint.
  """
  if type_constraint is None and object_instance is None:
    return
  elif isinstance(type_constraint, TypeConstraint):
    type_constraint.type_check(object_instance)
  elif type_constraint is None:
    # TODO(robertwb): Fix uses of None for Any.
    pass
  elif not isinstance(type_constraint, type):
    raise RuntimeError("bad type: %s" % (type_constraint, ))
  elif not isinstance(object_instance, type_constraint):
    raise SimpleTypeHintError


class AnyTypeConstraint(TypeConstraint):
  """An Any type-hint.

  Any is intended to be used as a "don't care" when hinting the types of
  function arguments or return types. All other TypeConstraint's are equivalent
  to 'Any', and its 'type_check' method is a no-op.
  """
  def __eq__(self, other):
    return type(self) == type(other)

  def __repr__(self):
    return 'Any'

  def __hash__(self):

View on GitHub (pinned to 12126d8942)