{"record":{"id":"468489a836aa09b4","repo":"pola-rs/polars","slug":"cannot-merge-sort-empty-list","errorCode":null,"errorMessage":"cannot merge_sort empty list","messagePattern":"cannot merge_sort empty list","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/functions/eager.py","lineNumber":761,"sourceCode":"    │ megan  ┆ 33  │\n    │ ida    ┆ 37  │\n    │ steve  ┆ 42  │\n    │ elise  ┆ 44  │\n    └────────┴─────┘\n\n\n    Notes\n    -----\n    Unless ``maintain_order=True``, no guarantee is given over the output\n    row order when the key is equal between dataframes.\n\n    The key(s) must be sorted in ascending order.\n    \"\"\"\n    elems: Sequence[PolarsType] = list(items)\n\n    if not elems:\n        msg = \"cannot merge_sort empty list\"\n        raise ValueError(msg)\n    if len(elems) == 1 and isinstance(elems[0], (pl.DataFrame, pl.LazyFrame)):\n        return elems[0]\n\n    if not is_non_empty_sequence_of(\n        elems, pl.DataFrame\n    ) and not is_non_empty_sequence_of(  # type: ignore[redundant-expr]\n        elems, pl.LazyFrame\n    ):\n        msg = f\"merge_sorted is not supported for {qualified_type_name(elems[0])!r}\"\n        raise TypeError(msg)\n\n    frames = [df.lazy() for df in elems]\n\n    def reduce_fn(x: pl.LazyFrame, y: pl.LazyFrame) -> pl.LazyFrame:\n        return x.merge_sorted(y, key=key, maintain_order=maintain_order)\n\n    lf = reduce_balanced(reduce_fn, frames)\n    eager = isinstance(elems[0], pl.DataFrame)","sourceCodeStart":743,"sourceCodeEnd":779,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/functions/eager.py#L743-L779","documentation":"Raised by pl.merge_sorted when `items` unpacks to zero elements. With nothing to merge there is no schema for the result, and returning an invented empty frame would hide bugs, so polars raises ValueError instead.","triggerScenarios":"pl.merge_sorted([], key='ts'); a comprehension of frames filtered to zero, e.g. [read(f) for f in paths if keep(f)] when nothing is kept; empty batch window in a streaming job.","commonSituations":"Scheduled jobs hitting an empty time window; glob that matched no files; conditional frame collection where no branch fired.","solutions":["Guard before the call and return a typed empty frame: pl.DataFrame(schema=schema) (plus .lazy() if the pipeline is lazy)","Fix the upstream source so at least one frame is produced","Treat 'no frames' as an explicit domain case in your pipeline rather than an error"],"exampleFix":"# before\nout = pl.merge_sorted(frames, key='ts')  # frames == []\n\n# after\nschema = {'ts': pl.Datetime, 'v': pl.Float64}\nout = pl.merge_sorted(frames, key='ts') if frames else pl.DataFrame(schema=schema).lazy()","handlingStrategy":"validation","validationCode":"frames = list(items)\nif not frames:\n    out = pl.DataFrame(schema=expected_schema).lazy()\nelse:\n    out = pl.merge_sorted(frames, key=key, maintain_order=maintain_order)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Materialize frame lists with list() and branch on emptiness","Verify the frame source (glob/filter/batch window) produced at least one frame"],"tags":["polars","merge-sorted","empty-input"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}