{"record":{"id":"17c2015f27aa4b20","repo":"apache/beam","slug":"type-hint-for-s-violated-expected-an-instance-of-s-instead","errorCode":null,"errorMessage":"Type-hint for %s violated. Expected an instance of %s, instead found %san instance of %s.","messagePattern":"Type-hint for (.+?) violated\\. Expected an instance of (.+?), instead found (.+?)an instance of (.+?)\\.","errorType":"validation","errorClass":"TypeCheckError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/decorators.py","lineNumber":1040,"sourceCode":"      'type_constraint'.\n    var_name: If 'instance' is an argument, then the actual name for the\n      parameter in the original function definition.\n\n  Raises:\n    TypeCheckError: If 'instance' fails to meet the type-constraint of\n      'type_constraint'.\n  \"\"\"\n  hint_type = (\n      \"argument: '%s'\" % var_name if var_name is not None else 'return type')\n\n  try:\n    check_constraint(type_constraint, instance)\n  except SimpleTypeHintError:\n    if verbose:\n      verbose_instance = '%s, ' % instance\n    else:\n      verbose_instance = ''\n    raise TypeCheckError(\n        'Type-hint for %s violated. Expected an '\n        'instance of %s, instead found %san instance of %s.' %\n        (hint_type, type_constraint, verbose_instance, type(instance)))\n  except CompositeTypeHintError as e:\n    raise TypeCheckError('Type-hint for %s violated: %s' % (hint_type, e))\n\n\ndef _interleave_type_check(type_constraint, var_name=None):\n  \"\"\"Lazily type-check the type-hint for a lazily generated sequence type.\n\n  This function can be applied as a decorator or called manually in a curried\n  manner:\n    * @_interleave_type_check(List[int])\n      def gen():\n        yield 5\n\n    or\n","sourceCodeStart":1022,"sourceCodeEnd":1058,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/decorators.py#L1022-L1058","documentation":"_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).","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\n@with_output_types(int)\ndef parse(s): return s  # s is str\n// after\n@with_output_types(int)\ndef parse(s): return int(s)","handlingStrategy":"try-catch","validationCode":"from apache_beam.typehints import check_constraint\ndef validate(instance, constraint):\n  check_constraint(constraint, instance)","typeGuard":"def matches_hint(instance, constraint):\n  try:\n    check_constraint(constraint, instance); return True\n  except Exception:\n    return False","tryCatchPattern":"try:\n  pcoll | check_or_interleave(hint)\nexcept TypeCheckError as e:\n  log.error('instance violates hint: %s', e)","preventionTips":["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"],"tags":["python","type-hints","apache-beam","runtime-validation"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}