{"record":{"id":"30e961df6b1aaed0","repo":"apache/beam","slug":"k-val","errorCode":null,"errorMessage":"k_val","messagePattern":"k_val","errorType":"exception","errorClass":"KeyError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/frames.py","lineNumber":1158,"sourceCode":"      dummy_index = (\n          pd.MultiIndex.from_tuples([k_val], names=proxy_frame.index.names) if\n          isinstance(k_val, tuple) else pd.Index([k_val],\n                                                 name=proxy_frame.index.name))\n\n      if isinstance(proxy_frame, pd.DataFrame):\n        dummy_obj = proxy_frame.reindex(dummy_index)\n        xs_proxy = dummy_obj.xs(k_val, **kwargs)\n        if isinstance(xs_proxy, (pd.DataFrame, pd.Series)):\n          xs_proxy = xs_proxy.iloc[:0]\n      else:\n        try:\n          xs_proxy = proxy_frame.dtype.type()\n        except TypeError:\n          xs_proxy = proxy_frame.reindex(dummy_index).iloc[0]\n\n      def unwrap_xs(ser):\n        if ser.empty:\n          raise KeyError(k_val)\n        return ser.iloc[0]\n\n      with expressions.allow_non_parallel_operations(True):\n        return frame_base.DeferredFrame.wrap(\n            expressions.ComputedExpression(\n                'xs',\n                unwrap_xs, [intermediate],\n                proxy=xs_proxy,\n                requires_partition_by=partitionings.Singleton(),\n                preserves_partition_by=partitionings.Singleton()))\n\n  @property\n  def dtype(self):\n    return self._expr.proxy().dtype\n\n  isin = frame_base._elementwise_method('isin', base=pd.DataFrame)\n  combine_first = frame_base._elementwise_method(\n      'combine_first', base=pd.DataFrame)","sourceCodeStart":1140,"sourceCodeEnd":1176,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/frames.py#L1140-L1176","documentation":"Inside unwrap_xs (used by DataFrame.xs in the Beam DataFrame API), this reference identifies the k_val field: the key being cross-sectioned. The surrounding code builds a dummy index from k_val and reindexes to emulate xs lazily; if k_val's type/value cannot be handled (e.g. reindexing fails), the wrapped error mentioning 'k_val' surfaces. It is a lazy-API implementation detail rather than a user-facing validation.","triggerScenarios":"df.xs(missing_key, level='lvl') where no row has that level value; xs after a filter that removed all matching rows; xs with a tuple key whose level values don't co-occur in any row.","commonSituations":"Typos in level values ('2023' vs 2023 type mismatches); data-dependent pipelines where a key present yesterday is absent today; xs on an empty intermediate frame.","solutions":["Check the key exists at the given level before xs (e.g. key in df.index.get_level_values(level))","Wrap in try/except KeyError and handle the missing-key case explicitly","Verify index dtypes match the key type (int vs str labels)"],"exampleFix":"// before\nrow = df.xs('2024', level='year')\n// after\nif '2024' in df.index.get_level_values('year'):\n    row = df.xs('2024', level='year')\nelse:\n    row = None","handlingStrategy":"try-catch","validationCode":"level_vals = df.index.get_level_values(level) if level is not None else df.index\nif not all(k in level_vals for k in (key if isinstance(key, tuple) else (key,))):\n    raise KeyError(f\"xs key {key!r} not present in index\")","typeGuard":"def key_in_index(df, key, level=None):\n    vals = df.index.get_level_values(level) if level is not None else df.index\n    return key in vals","tryCatchPattern":"try:\n    out = df.xs(key, level=level)\nexcept KeyError as e:\n    logging.warning(\"xs key %s missing, returning empty\", key)\n    out = df.iloc[0:0]","preventionTips":["Confirm the key exists at the target level before xs","Match key types with index dtypes (int vs str)","Handle the possibility of empty frames after upstream filters"],"tags":["python","apache-beam","dataframe","keyerror"],"backgroundTag":"resource-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}