{"record":{"id":"7b4b43a7527c7414","repo":"apache/beam","slug":"unexpected-var-keyword-value-s","errorCode":null,"errorMessage":"Unexpected VAR_KEYWORD value: %s","messagePattern":"Unexpected VAR_KEYWORD value: (.+?)","errorType":"validation","errorClass":"TypeCheckError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/decorators.py","lineNumber":747,"sourceCode":"  else:\n    # Example: tuple(int, str) -> Tuple[Union[int, str], ...]\n    return typehints.Tuple[typehints.Union[hint], ...]\n\n\ndef _normalize_var_keyword_hint(hint, arg_name):\n  \"\"\"Converts a var_keyword hint into Dict[<key type>, <value type>] form.\n\n  Args:\n    hint: (dict) Should either contain a pair (arg_name,\n      Dict[<key type>, <value type>]), or one or more possible types for the\n      value.\n    arg_name: (str) The keyword receiving this hint.\n\n  Raises:\n    TypeCheckError if hint does not have the right form.\n  \"\"\"\n  if not hint or type(hint) != dict:\n    raise TypeCheckError('Unexpected VAR_KEYWORD value: %s' % hint)\n  keys = list(hint.keys())\n  values = list(hint.values())\n  if (len(values) == 1 and keys[0] == arg_name and\n      isinstance(values[0], typehints.DictConstraint)):\n    # Example: dict(kwargs=Dict[str, Any]) -> Dict[str, Any]\n    return values[0]\n  else:\n    # Example: dict(k1=str, k2=int) -> Dict[str, Union[str,int]]\n    return typehints.Dict[str, typehints.Union[values]]\n\n\ndef getcallargs_forhints(func, *type_args, **type_kwargs):\n  \"\"\"Bind type_args and type_kwargs to func.\n\n  Works like inspect.getcallargs, with some modifications to support type hint\n  checks.\n  For unbound args, will use annotations and fall back to Any (or variants of\n  Any).","sourceCodeStart":729,"sourceCodeEnd":765,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/decorators.py#L729-L765","documentation":"_normalize_var_keyword_hint normalizes the hint for a **kwargs parameter into a Dict constraint. It requires a non-empty dict whose single entry maps the kwarg parameter name to a DictConstraint; any other form (None, empty dict, wrong key, non-DictConstraint value) raises TypeCheckError.","triggerScenarios":"getcallargs_forhints on a function with **kwargs where the stored hint is not dict(kwargs=Dict[...]) — e.g. hint is a bare Dict[str, Any] (unwrapped), an empty dict, or keyed by a different name than arg_name.","commonSituations":"Hand-assembled IOTypeHints where the VAR_KEYWORD slot was set to a DictConstraint directly instead of the wrapper dict; serialized hints from a different Beam version; typos in the kwarg name key.","solutions":["Store the hint as {arg_name: Dict[key_type, value_type]} so keys[0]==arg_name and the value is a DictConstraint","Unwrap manually: if you have a bare DictConstraint, wrap it in a dict keyed by the kwargs parameter name","Use the standard decorators (with_input_types / type annotations) rather than building hint structures by hand","Log/inspect the failing hint dict and verify its single key matches the parameter name"],"exampleFix":"// before\nhints.var_keyword_arg = Dict[str, Any]\n// after\nhints.var_keyword_arg = {'kwargs': Dict[str, Any]}","handlingStrategy":"validation","validationCode":"def is_valid_var_keyword(h, name):\n  return isinstance(h, dict) and list(h.keys()) == [name]","typeGuard":null,"tryCatchPattern":"try:\n  args = getcallargs_forhints(fn, hints)\nexcept TypeCheckError as e:\n  log.error('bad VAR_KEYWORD hint: %s', e)","preventionTips":["Store **kwargs hints as {param_name: Dict[K, V]}","Ensure the dict key equals the kwargs parameter name","Avoid hand-constructing hint structures"],"tags":["python","type-hints","apache-beam"],"backgroundTag":"invalid-argument-format","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"}