{"record":{"id":"72667709b6f7d0f1","repo":"pola-rs/polars","slug":"how-r-strategy-requires-at-least-one-common-colu","errorCode":null,"errorMessage":"{how!r} strategy requires at least one common column","messagePattern":"(.+?) strategy requires at least one common column","errorType":"exception","errorClass":"InvalidOperationError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/functions/eager.py","lineNumber":250,"sourceCode":"        ):\n            msg = f\"{how!r} strategy is not supported for {qualified_type_name(elems[0])!r}\"\n            raise TypeError(msg)\n\n        # establish common columns, maintaining the order in which they appear\n        all_columns = list(chain.from_iterable(e.collect_schema() for e in elems))\n        key = {v: k for k, v in enumerate(ordered_unique(all_columns))}\n        output_column_order = list(key)\n        common_cols = sorted(\n            reduce(\n                lambda x, y: set(x) & set(y),  # type: ignore[arg-type, return-value]\n                chain(e.collect_schema() for e in elems),\n            ),\n            key=lambda k: key.get(k, 0),\n        )\n        # we require at least one key column for 'align' strategies\n        if not common_cols:\n            msg = f\"{how!r} strategy requires at least one common column\"\n            raise InvalidOperationError(msg)\n\n        # align frame data using a join, with no suffix-resolution (will raise\n        # a DuplicateError in case of column collision, same as \"horizontal\")\n        join_method: JoinStrategy = (\n            \"full\" if how == \"align\" else how.removeprefix(\"align_\")  # type: ignore[assignment]\n        )\n        join_frames = [df.lazy() for df in elems]\n\n        def join_fn(x: pl.LazyFrame, y: pl.LazyFrame) -> pl.LazyFrame:\n            return x.join(\n                y,\n                on=common_cols,\n                how=join_method,\n                maintain_order=\"right_left\",\n                coalesce=True,\n            )\n\n        if join_method in (\"full\", \"inner\"):","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/functions/eager.py#L232-L268","documentation":"The align-family concat strategies join frames on the column names shared by every input. If the intersection of all input schemas is empty there is no key to align on, and Polars raises InvalidOperationError before executing the join. Column-name matching is exact (case- and whitespace-sensitive).","triggerScenarios":"pl.concat([df1, df2], how='align') where df1 has columns ['a','b'] and df2 has ['c','d']; case-mismatched names ('Id' vs 'id'); trailing whitespace in headers from CSVs; a rename applied to one frame upstream.","commonSituations":"Merging monthly extracts whose schemas drifted over time; case/whitespace differences from different data sources; accidental renames before the align call; assuming align does outer-horizontal concat instead of key-based alignment.","solutions":["Inspect schemas per frame and intersect them: set(df1.columns) & set(df2.columns) to find the mismatch","Rename to common keys before concat: df2.rename({'c': 'a'})","Normalize headers first (strip/lower) when sources are inconsistent","If no shared key was intended, use how='horizontal' instead of an align strategy"],"exampleFix":"# before\npl.concat([df1, df2], how='align')  # no common columns\n\n# after\ndf2 = df2.rename({'c': 'a'})\npl.concat([df1, df2], how='align')\n\n# or, if no key was intended:\npl.concat([df1, df2], how='horizontal')","handlingStrategy":"validation","validationCode":"schemas = [set(f.collect_schema().names()) if hasattr(f, 'collect_schema') else set(f.columns) for f in frames]\ncommon = set.intersection(*schemas) if schemas else set()\nif how.startswith('align') and not common:\n    raise ValueError(f'no common columns to align on: {[sorted(s) for s in schemas]}')\nout = pl.concat(frames, how=how)","typeGuard":null,"tryCatchPattern":"import polars as pl\n\ntry:\n    out = pl.concat(frames, how='align')\nexcept pl.exceptions.InvalidOperationError as e:\n    if 'common column' not in str(e):\n        raise\n    out = pl.concat(frames, how='horizontal')  # deliberate fallback","preventionTips":["Print the per-frame column sets when align fails and diff them","Normalize header case and whitespace at ingestion","Rename keys explicitly before aligning rather than relying on luck"],"tags":["polars","concat","align","schema-mismatch","invalidoperationerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}