apache/beam · error · TypeCheckError

Type-hint for violated. Expected an instance of , instead…

Error message

Type-hint for %s violated. Expected an instance of %s, instead found %san instance of %s.

What it means

_check_instance_type verifies a runtime value against a simple type-hint constraint. On SimpleTypeHintError it raises TypeCheckError stating the expected type and the actual type of the offending instance; on composite-hint failure it delegates (see 3928).

Solutions

Fix the runtime value (coerce/convert it) so it matches the declared hint, e.g. int(x) before emitting
Update the hint to reflect the actual data type: with_output_types(str) if values really are strings
Find the offending instance via the verbose message (enable verbose=True in type_check to print the instance)
Narrow the hint with Union or Optional[...] if both shapes are legitimately possible

Example fix

// before
@with_output_types(int)
def parse(s): return s  # s is str
// after
@with_output_types(int)
def parse(s): return int(s)

Defensive patterns

Strategy: try-catch

Validate before calling

from apache_beam.typehints import check_constraint
def validate(instance, constraint):
  check_constraint(constraint, instance)

Type guard

def matches_hint(instance, constraint):
  try:
    check_constraint(constraint, instance); return True
  except Exception:
    return False

Try / catch

try:
  pcoll | check_or_interleave(hint)
except TypeCheckError as e:
  log.error('instance violates hint: %s', e)

Prevention

Coerce data to hinted types at pipeline boundaries
Enable verbose=True to identify offending instances
Keep hints in sync with upstream transform outputs
Use Optional/Union where None or mixed types are possible

When it happens

Trigger: type_check / wrapper / process / add_input / extract_output / check_or_interleave receive a value violating an attached hint, e.g. emitting str from a DoFn hinted to output int, or adding an element of the wrong type to a hinted PTransform input.

Common situations: Runtime data diverging from declared hints — JSON fields parsed as str but hinted int, None where a concrete type was declared, upstream transform changed its output type without updating downstream hints.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/typehints/decorators.py:1040

      'type_constraint'.
    var_name: If 'instance' is an argument, then the actual name for the
      parameter in the original function definition.

  Raises:
    TypeCheckError: If 'instance' fails to meet the type-constraint of
      'type_constraint'.
  """
  hint_type = (
      "argument: '%s'" % var_name if var_name is not None else 'return type')

  try:
    check_constraint(type_constraint, instance)
  except SimpleTypeHintError:
    if verbose:
      verbose_instance = '%s, ' % instance
    else:
      verbose_instance = ''
    raise TypeCheckError(
        'Type-hint for %s violated. Expected an '
        'instance of %s, instead found %san instance of %s.' %
        (hint_type, type_constraint, verbose_instance, type(instance)))
  except CompositeTypeHintError as e:
    raise TypeCheckError('Type-hint for %s violated: %s' % (hint_type, e))


def _interleave_type_check(type_constraint, var_name=None):
  """Lazily type-check the type-hint for a lazily generated sequence type.

  This function can be applied as a decorator or called manually in a curried
  manner:
    * @_interleave_type_check(List[int])
      def gen():
        yield 5

    or

View on GitHub (pinned to 12126d8942)