{"record":{"id":"a436fb73f7b8f1bc","repo":"pola-rs/polars","slug":"cannot-use-include-key-without-specifying-key","errorCode":null,"errorMessage":"cannot use 'include_key' without specifying 'key'","messagePattern":"cannot use 'include_key' without specifying 'key'","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/partition.py","lineNumber":115,"sourceCode":"    ) -> None:\n        msg = \"`PartitionBy` functionality is considered unstable\"\n        issue_unstable_warning(msg)\n\n        if (\n            key is None\n            and max_rows_per_file is None\n            and approximate_bytes_per_file == \"auto\"\n        ):\n            msg = (\n                \"at least one of \"\n                \"('key', 'max_rows_per_file', 'approximate_bytes_per_file') \"\n                \"must be specified for PartitionBy\"\n            )\n            raise ValueError(msg)\n\n        if key is None and include_key is not None:\n            msg = \"cannot use 'include_key' without specifying 'key'\"\n            raise ValueError(msg)\n\n        base_path = str(base_path)\n\n        if approximate_bytes_per_file == \"auto\":\n            approximate_bytes_per_file = (\n                4_294_967_295 if max_rows_per_file is None else None\n            )\n\n        if approximate_bytes_per_file is None:\n            approximate_bytes_per_file = (1 << 64) - 1\n\n        self._pl_partition_by = _PartitionByInner(\n            base_path=base_path,\n            file_path_provider=file_path_provider,\n            key=_parse_to_pyexpr_list(key) if key is not None else None,\n            include_key=include_key,\n            max_rows_per_file=max_rows_per_file,\n            approximate_bytes_per_file=approximate_bytes_per_file,","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/partition.py#L97-L133","documentation":"ValueError raised by the PartitionBy constructor when include_key is set but key is None. include_key controls whether the partition-key column(s) are also written into the output files; with no key there is nothing to include or omit, so the option is meaningless and rejected at construction time.","triggerScenarios":"pl.PartitionBy('out/', max_rows_per_file=1000, include_key=True) — any size-only or byte-only partitioning combined with include_key.","commonSituations":"Copy-pasting a keyed PartitionBy config and removing the key while keeping include_key; setting include_key=True 'for completeness' when only chunking by size; config templates that always populate include_key.","solutions":["Remove include_key when partitioning only by size: pl.PartitionBy('out/', max_rows_per_file=1000).","Or add a key so include_key becomes meaningful: pl.PartitionBy('out/', key='region', include_key=False).","Audit shared config dicts so include_key is only injected when a key is present."],"exampleFix":"# before\npl.PartitionBy('out/', max_rows_per_file=1_000_000, include_key=True)\n\n# after\npl.PartitionBy('out/', max_rows_per_file=1_000_000)\n# or\npl.PartitionBy('out/', key='region', include_key=True)","handlingStrategy":"validation","validationCode":"cfg = dict(partition_cfg)\nif cfg.get('key') is None:\n    cfg.pop('include_key', None)  # meaningless without a key\npl.PartitionBy(base_path, **cfg)","typeGuard":null,"tryCatchPattern":"try:\n    pl.PartitionBy(out_dir, **cfg)\nexcept ValueError as e:\n    if \"without specifying 'key'\" in str(e):\n        cfg.pop('include_key', None)\n        pl.PartitionBy(out_dir, **cfg)\n    else:\n        raise","preventionTips":["Only populate include_key in configs that also populate key.","Model partition config as a dataclass where include_key validity is checked in __post_init__.","Size-based chunking and include_key are unrelated — do not copy options between them blindly."],"tags":["parquet","sink","partitioning","write","parameter-validation"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}