pola-rs/polars · error · ValueError

at least one of ('key', 'max_rows_per_file'…

Error message

at least one of ('key', 'max_rows_per_file', 'approximate_bytes_per_file') must be specified for PartitionBy

What it means

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.

Solutions

1. Pass a key (or list of keys): pl.PartitionByKey/base_path with key='col'
2. Set max_rows_per_file (e.g. 100_000) to split by row count
3. Set approximate_bytes_per_file to split by file size
4. Fix keyword typos / ensure config values are actually populated

Example fix

// before
partition = pl.PartitionBy('out/')
// after
partition = pl.PartitionBy('out/', key='date')

if key is None and max_rows_per_file is None and approximate_bytes_per_file is None:
    raise ValueError('PartitionBy needs key, max_rows_per_file, or approximate_bytes_per_file')

try:
    pt = pl.PartitionBy(base, key=k, max_rows_per_file=m)
except ValueError as e:
    if 'must be specified for PartitionBy' in str(e):
        pt = pl.PartitionBy(base, key=k or 'partition_key')

When it happens

Trigger: 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).

Common situations: Building PartitionBy dynamically from config where all partitioning options were left unset; typos in keyword names silently leaving key=None.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• cannot use 'include_key' without specifying 'key'
• Categorical physical must be one of pl.UInt(8|16|32)
• Enum categories must be unique; found duplicate
• Enum categories must not contain null values
• 'infer_schema_length' should be positive

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/ced195adbdb84e77. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/io/partition.py:111

        key: str | Expr | Sequence[str | Expr] | Mapping[str, Expr] | None = None,
        include_key: bool | None = None,
        max_rows_per_file: int | None = None,
        approximate_bytes_per_file: int | Literal["auto"] | None = "auto",
    ) -> None:
        msg = "`PartitionBy` functionality is considered unstable"
        issue_unstable_warning(msg)

        if (
            key is None
            and max_rows_per_file is None
            and approximate_bytes_per_file == "auto"
        ):
            msg = (
                "at least one of "
                "('key', 'max_rows_per_file', 'approximate_bytes_per_file') "
                "must be specified for PartitionBy"
            )
            raise ValueError(msg)

        if key is None and include_key is not None:
            msg = "cannot use 'include_key' without specifying 'key'"
            raise ValueError(msg)

        base_path = str(base_path)

        if approximate_bytes_per_file == "auto":
            approximate_bytes_per_file = (
                4_294_967_295 if max_rows_per_file is None else None
            )

        if approximate_bytes_per_file is None:
            approximate_bytes_per_file = (1 << 64) - 1

        self._pl_partition_by = _PartitionByInner(
            base_path=base_path,
            file_path_provider=file_path_provider,

View on GitHub (pinned to fe841f959e)