{"record":{"id":"ced195adbdb84e77","repo":"pola-rs/polars","slug":"at-least-one-of-key-max-rows-per-file-appr","errorCode":null,"errorMessage":"at least one of ('key', 'max_rows_per_file', 'approximate_bytes_per_file') must be specified for PartitionBy","messagePattern":"at least one of \\('key', 'max_rows_per_file', 'approximate_bytes_per_file'\\) must be specified for PartitionBy","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/partition.py","lineNumber":111,"sourceCode":"        key: str | Expr | Sequence[str | Expr] | Mapping[str, Expr] | None = None,\n        include_key: bool | None = None,\n        max_rows_per_file: int | None = None,\n        approximate_bytes_per_file: int | Literal[\"auto\"] | None = \"auto\",\n    ) -> 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,","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/io/partition.py#L93-L129","documentation":"A PartitionBy target must know how to split data: it needs at least a partition key, a row limit per file, or a byte-size target. Constructing one with none of these is meaningless, so __init__ raises ValueError.","triggerScenarios":"pl.PartitionBy(base_path, ...) where key is None, max_rows_per_file is None, and approximate_bytes_per_file is None (or explicitly passed as None).","commonSituations":"Building PartitionBy dynamically from config where all partitioning options were left unset; typos in keyword names silently leaving key=None.","solutions":["Pass a key (or list of keys): pl.PartitionByKey/base_path with key='col'","Set max_rows_per_file (e.g. 100_000) to split by row count","Set approximate_bytes_per_file to split by file size","Fix keyword typos / ensure config values are actually populated"],"exampleFix":"// before\npartition = pl.PartitionBy('out/')\n// after\npartition = pl.PartitionBy('out/', key='date')","handlingStrategy":"validation","validationCode":"if key is None and max_rows_per_file is None and approximate_bytes_per_file is None:\n    raise ValueError('PartitionBy needs key, max_rows_per_file, or approximate_bytes_per_file')","typeGuard":null,"tryCatchPattern":"try:\n    pt = pl.PartitionBy(base, key=k, max_rows_per_file=m)\nexcept ValueError as e:\n    if 'must be specified for PartitionBy' in str(e):\n        pt = pl.PartitionBy(base, key=k or 'partition_key')","preventionTips":["Always pass at least one partitioning dimension","Validate config keys (typos leave key=None)","Build PartitionBy args from a checked config schema"],"tags":["polars","partitioning","validation"],"backgroundTag":"missing-required-argument","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}