{"record":{"id":"08bf508fb691b579","repo":"apache/beam","slug":"type-hint-for-s-violated-s","errorCode":null,"errorMessage":"Type-hint for %s violated: %s","messagePattern":"Type-hint for (.+?) violated: (.+?)","errorType":"validation","errorClass":"TypeCheckError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/decorators.py","lineNumber":1045,"sourceCode":"    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\n     * gen = _interleave_type_check(Tuple[int, int], 'coord_gen')(gen)\n\n  As a result, all type-checking for the passed generator will occur at 'yield'\n  time. This way, we avoid having to depleat the generator in order to\n  type-check it.","sourceCodeStart":1027,"sourceCodeEnd":1063,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/decorators.py#L1027-L1063","documentation":"When a composite type-hint (container/generator/union constraint) is violated, _check_instance_type catches CompositeTypeHintError and re-raises it as TypeCheckError 'Type-hint for %s violated: %s', preserving the detailed sub-constraint failure from the composite checker.","triggerScenarios":"A value passes its top-level type but fails inside the composite constraint, e.g. hinted List[int] but the list contains a str, or Dict[str, int] with a float value — raised from type_check, wrapper, process, add_input, extract_output, or check_or_interleave.","commonSituations":"Nested-container data with one bad element (a single malformed record in a batch); Optional/Union hints where the value matches none of the branches; elements produced by a changed upstream transform.","solutions":["Read the embedded CompositeTypeHintError detail in the message to locate the failing sub-element","Fix or filter the offending element before it reaches the type-checked boundary","Loosen the composite hint (List[Any], Union branches) if the data legitimately varies","Add a Map/DoFn validation step upstream to sanitize elements before the hinted transform"],"exampleFix":"// before\n@with_output_types(List[int])\ndef f(): return [1, 'two']\n// after\n@with_output_types(List[int])\ndef f(): return [1, int('2')]  # or hint List[Union[int, str]]","handlingStrategy":"validation","validationCode":"def validate_elements(items, elem_constraint):\n  for i, x in enumerate(items):\n    try:\n      check_constraint(elem_constraint, x)\n    except Exception as e:\n      raise ValueError(f'element {i} bad: {e}')","typeGuard":"def all_match(items, constraint):\n  return all(matches_hint(x, constraint) for x in items)","tryCatchPattern":"try:\n  pcoll | check_or_interleave(hint)\nexcept TypeCheckError as e:\n  log.error('composite hint violated: %s', e)  # detail names the sub-element","preventionTips":["Sanitize/normalize records before type-checked stages","Read the nested detail in the message to find the bad element","Loosen container hints with Union/Any where data legitimately varies"],"tags":["python","type-hints","apache-beam","runtime-validation"],"backgroundTag":"schema-validation-failed","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"}