{"record":{"id":"a19d4d3b6543f2e4","repo":"pola-rs/polars","slug":"map-requires-a-key-and-a-value-type-e-g-pl-map","errorCode":null,"errorMessage":"Map requires a key and a value type, e.g. `pl.Map(pl.String, pl.Int64)`","messagePattern":"Map requires a key and a value type, e\\.g\\. `pl\\.Map\\(pl\\.String, pl\\.Int64\\)`","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_utils/construction/series.py","lineNumber":203,"sourceCode":"            elif pyseries.dtype().is_integer() or pyseries.dtype() == Null:\n                pyseries = pyseries.cast(\n                    Decimal(scale=0), strict=strict, wrap_numerical=False\n                )\n            elif not isinstance(pyseries.dtype(), Decimal):\n                msg = f\"can't convert {pyseries.dtype()} to Decimal\"\n                raise TypeError(msg)\n\n        return pyseries\n\n    elif isinstance(dtype, Map):\n        # A dict is otherwise inferred as a Struct, so the Map dtype has to drive this.\n        return PySeries.new_from_any_values_and_dtype(\n            name, values, dtype, strict=strict\n        )\n\n    elif dtype == Map:\n        msg = \"Map requires a key and a value type, e.g. `pl.Map(pl.String, pl.Int64)`\"\n        raise TypeError(msg)\n\n    elif dtype == Struct:\n        # This is very bad. Goes via rows? And needs to do outer nullability separate.\n        # It also has two data passes.\n        # TODO: eventually go into struct builder\n        struct_schema = dtype.to_schema() if isinstance(dtype, Struct) else None\n        empty = {}  # type: ignore[var-annotated]\n\n        data = []\n        invalid = []\n        for i, v in enumerate(values):\n            if v is None:\n                invalid.append(i)\n                data.append(empty)\n            else:\n                data.append(v)\n\n        return plc.sequence_to_pydf(","sourceCodeStart":185,"sourceCodeEnd":221,"githubUrl":"https://github.com/pola-rs/polars/blob/68506541d2de983056c9eb244e1ea05fab377dfc/py-polars/src/polars/_utils/construction/series.py#L185-L221","documentation":"When constructing a Series with an explicit Map dtype from a Python sequence, Polars requires the dtype to carry both a key and a value type (e.g. pl.Map(pl.String, pl.Int64)). A bare `pl.Map` has no key/value types, so the values cannot be converted and a TypeError is raised.","triggerScenarios":"Calling pl.Series(name, values, dtype=pl.Map) (or any API that funnels into sequence_to_pyseries, such as DataFrame construction or __setitem__) with dtype equal to the bare Map class instead of an instantiated pl.Map(key_dtype, value_dtype).","commonSituations":"Passing `pl.Map` where other dtypes like pl.List or pl.Struct work bare; copying dtype declarations from docs without arguments; dynamically building dtypes from schema strings like 'map' without arguments.","solutions":["Instantiate the dtype with key and value types: use pl.Map(pl.String, pl.Int64) (or your key/value dtypes).","If the data is a list of dicts, consider pl.List(pl.Struct({...})) instead — struct handles heterogeneous records and nullability better.","Check the dtype is being read from configuration/schema with its parameters intact rather than just the class name."],"exampleFix":"// before\ns = pl.Series(\"m\", [{\"a\": 1}], dtype=pl.Map)\n// after\ns = pl.Series(\"m\", [{\"a\": 1}], dtype=pl.Map(pl.String, pl.Int64))","handlingStrategy":"type-guard","validationCode":"import polars as pl\ndef is_instantiated_map(dtype) -> bool:\n    return isinstance(dtype, pl.Map) and dtype is not pl.Map\ndef validate_map_dtype(dtype):\n    if dtype is Map:\n        raise TypeError(\"use pl.Map(key_dtype, value_dtype), not bare pl.Map\")\n    return dtype","typeGuard":"def is_parameterized_map(dtype) -> bool:\n    return isinstance(dtype, pl.Map) and dtype is not pl.Map","tryCatchPattern":"try:\n    s = pl.Series(name, values, dtype=dtype)\nexcept TypeError as e:\n    if \"Map requires a key and a value type\" in str(e):\n        dtype = pl.Map(pl.String, pl.Int64)\n        s = pl.Series(name, values, dtype=dtype)\n    else:\n        raise","preventionTips":["Always instantiate Map with key and value dtypes","Never pass bare dtype classes that require parameters (Map, List) — use instances","Consider List(Struct) for record-like data instead of Map","Validate dtypes parsed from config carry their parameters"],"tags":["python","types","map-dtype","series-construction"],"backgroundTag":"invalid-argument-value","analyzedSha":"68506541d2de983056c9eb244e1ea05fab377dfc","analyzedAt":"2026-09-10T10:08:55.499Z","contentChangedAt":"2026-09-10T10:08:55.499Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}