pola-rs/polars · error · ValueError

`n_chunks` must be a multiple of the number of chunks of thi

Error message

`n_chunks` must be a multiple of the number of chunks of this dataframe ({total_n_chunks})

What it means

Raised by PolarsDataFrame.get_chunks when n_chunks is <= 0 or not an integer multiple of the dataframe's actual chunk count. Chunk production derives from column 0's chunks and can only subdivide each evenly, so requests must align with num_chunks().

Source

Thrown at py-polars/src/polars/interchange/dataframe.py:194

        -----
        When the columns in the dataframe are chunked unevenly, or when `n_chunks` is
        higher than the number of chunks in the dataframe, a slice must be performed
        that is not on the chunk boundary. This will trigger some compute for columns
        that contain null values and boolean columns.
        """
        total_n_chunks = self.num_chunks()
        chunks = self._get_chunks_from_col_chunks()

        if (n_chunks is None) or (n_chunks == total_n_chunks):
            for chunk in chunks:
                yield PolarsDataFrame(chunk, allow_copy=self._allow_copy)

        elif (n_chunks <= 0) or (n_chunks % total_n_chunks != 0):
            msg = (
                "`n_chunks` must be a multiple of the number of chunks of this"
                f" dataframe ({total_n_chunks})"
            )
            raise ValueError(msg)

        else:
            subchunks_per_chunk = n_chunks // total_n_chunks
            for chunk in chunks:
                size = len(chunk)
                step = size // subchunks_per_chunk
                if size % subchunks_per_chunk != 0:
                    step += 1
                for start in range(0, step * subchunks_per_chunk, step):
                    yield PolarsDataFrame(
                        chunk[start : start + step, :],
                        allow_copy=self._allow_copy,
                    )

    def _get_chunks_from_col_chunks(self) -> Iterator[DataFrame]:
        """
        Return chunks of this dataframe according to the chunks of the first column.

View on GitHub (pinned to df599052da)

Solutions

1. Call get_chunks() with n_chunks=None and batch on the consumer side
2. Request a multiple of the frame's chunk count: dfi.num_chunks() * k
3. Ensure n_chunks > 0 and validated against num_chunks() before requesting

Example fix

// before
for chunk in dfi.get_chunks(7):  # frame has 3 chunks
    ...
// after
for chunk in dfi.get_chunks():
    ...  # batch downstream at whatever size you need

total = dfi.num_chunks()
ok = n_chunks is None or (n_chunks > 0 and n_chunks % total == 0)

def is_valid_df_chunk_request(n_chunks: int, total: int) -> bool:
    return n_chunks > 0 and n_chunks % total == 0

try:
    for chunk in dfi.get_chunks(n_chunks):
        ...
except ValueError:
    for chunk in dfi.get_chunks():
        ...

When it happens

Trigger: dfi.get_chunks(4) on a frame with 3 chunks; passing 0 or negative counts; batching logic that requests a consumer-chosen chunk count unrelated to the source chunking.

Common situations: Streaming consumers requesting chunks sized to their own batch windows; frames assembled from multiple scans/concats yielding non-divisible chunk counts; interleaving dataframe chunks with per-column get_chunks calls under mismatched assumptions.

Related errors

• `n_chunks` must be a multiple of the number of chunks of thi
• non-contiguous buffer must be made contiguous
• unevenly chunked columns must be rechunked
• "pad_start" expects a `str`, given a {qualified_type_name(fi
• "pad_end" expects a `str`, given a {qualified_type_name(fill

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/04a0a4b45cfb6ff5. Report an issue: GitHub.