pola-rs/polars · error · ValueError

cannot use 'include_key' without specifying 'key'

Error message

cannot use 'include_key' without specifying 'key'

What it means

include_key controls whether partition-key columns are repeated inside the output data, so it only makes sense when a key is defined. Passing include_key without key is contradictory and raises ValueError in PartitionBy.__init__.

Solutions

1. Specify a key alongside include_key: pl.PartitionBy('out/', key='col', include_key=False)
2. Remove the include_key argument when there is no key
3. Fix the variable feeding key so it is not None

Example fix

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

if include_key is not None and key is None:
    raise ValueError('include_key requires a partition key')

When it happens

Trigger: pl.PartitionBy(base_path, key=None, include_key=True/False) — any non-None include_key while key is None.

Common situations: Copy-pasting include_key=True from keyed partition configs; templated code that always passes include_key even when key is unset.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• at least one of ('key', 'max_rows_per_file'…
• 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/a436fb73f7b8f1bc. Report an issue: GitHub.

Appendix: source

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

    ) -> 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,
            key=_parse_to_pyexpr_list(key) if key is not None else None,
            include_key=include_key,
            max_rows_per_file=max_rows_per_file,
            approximate_bytes_per_file=approximate_bytes_per_file,

View on GitHub (pinned to fe841f959e)