{"record":{"id":"b444920ecb96ae2e","repo":"apache/beam","slug":"length-of-parameters-to-a-kv-type-hint-must-be-exactly-2","errorCode":null,"errorMessage":"Length of parameters to a KV type-hint must be exactly 2. Passed parameters: %s, have a length of %s.","messagePattern":"Length of parameters to a KV type-hint must be exactly 2\\. Passed parameters: (.+?), have a length of (.+?)\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":829,"sourceCode":"\nListConstraint = ListHint.ListConstraint\n\n\nclass KVHint(CompositeTypeHint):\n  \"\"\"A KV type-hint, represents a Key-Value pair of a particular type.\n\n  Internally, KV[X, Y] proxies to Tuple[X, Y]. A KV type-hint accepts only\n  accepts exactly two type-parameters. The first represents the required\n  key-type and the second the required value-type.\n  \"\"\"\n  def __getitem__(self, type_params):\n    if not isinstance(type_params, tuple):\n      raise TypeError(\n          'Parameter to KV type-hint must be a tuple of types: '\n          'KV[.., ..].')\n\n    if len(type_params) != 2:\n      raise TypeError(\n          'Length of parameters to a KV type-hint must be exactly 2. Passed '\n          'parameters: %s, have a length of %s.' %\n          (type_params, len(type_params)))\n\n    return Tuple[type_params]\n\n\ndef key_value_types(kv):\n  \"\"\"Returns the key and value type of a KV type-hint.\n\n  Args:\n    kv: An instance of a TypeConstraint sub-class.\n  Returns:\n    A tuple: (key_type, value_type) if the passed type-hint is an instance of a\n    KV type-hint, and (Any, Any) otherwise.\n  \"\"\"\n  if isinstance(kv, TupleHint.TupleConstraint):\n    return kv.tuple_types","sourceCodeStart":811,"sourceCodeEnd":847,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L811-L847","documentation":"KVHint.__getitem__ received a tuple of type parameters whose length is not 2; a KV hint denotes exactly a key type and a value type, so KV[str, int, float] (or an empty KV[]) is rejected at typehint-construction time.","triggerScenarios":"KV[int] — bare non-tuple single param actually hits the earlier check, but KV[(int,)] or KV[(int, str, bool)] (parenthesized 1- or 3-tuple) triggers this; dynamically building params with wrong count.","commonSituations":"Programmatic hint construction (e.g. KV[tuple(fields)]) where fields has != 2 items; misunderstanding that KV[int, str, bool] parses as a 3-tuple.","solutions":["Ensure exactly two type parameters: KV[int, str]","If the key/value pair comes from data, validate len==2 before subscripting","Split extra fields out or compose nested types, e.g. KV[int, Tuple[str, bool]]"],"exampleFix":"# before\nKV[(int, str, bool)]\n# after\nKV[int, Tuple[str, bool]]","handlingStrategy":"validation","validationCode":"if len(params) != 2: raise ValueError(f'KV needs exactly 2 params, got {len(params)}')","typeGuard":"def is_pair(t): return isinstance(t, tuple) and len(t) == 2","tryCatchPattern":null,"preventionTips":["Assert parameter count before constructing KV hints dynamically","Compose extra fields into nested Tuple[...] types instead of adding params"],"tags":["python","apache-beam","type-hints","kv"],"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"}