pola-rs/polars · error · TypeError

Array constructor is missing the required argument `shape`

Error message

Array constructor is missing the required argument `shape`

What it means

pl.Array requires an explicit `shape` (a fixed-width nested type, unlike List). Since 1.x the constructor no longer infers shape from data, so constructing pl.Array(inner) without shape raises this TypeError.

Solutions

1. Pass shape as an int for 1-D: pl.Array(pl.Int32, 3)
2. Pass a tuple for nested shapes: pl.Array(pl.Int32, (2, 3))
3. Use pl.List instead if the width is truly variable

Example fix

// before
pl.Array(pl.Int32)
// after
pl.Array(pl.Int32, shape=3)

def make_array(inner, shape=None):
    if shape is None:
        raise ValueError('pl.Array requires an explicit shape')
    return pl.Array(inner, shape=shape)

try:
    dtype = pl.Array(inner, shape)
except TypeError as e:
    if 'shape' in str(e):
        dtype = pl.List(inner)  # variable width fallback
    else:
        raise

When it happens

Trigger: pl.Array(pl.Int32) with no shape argument; pl.Array(pl.Float64, shape=None) explicitly; copying old pre-1.0 code where width was optional.

Common situations: Upgrading polars across versions where the Array signature changed; converting pl.List usages to pl.Array and forgetting the width.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• arr.to_struct() got a str instead of a list. hint: pass
• cannot call `map_groups` when filtering groups with `having`
• cannot call `map_groups` when grouping by an expression
• cannot call `map_groups` when grouping by named expressions
• cannot create DataFrame from array with more than two…

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/ead5b3c50bf2bf03. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/datatypes/classes.py:1247

    size: int
    shape: tuple[int, ...]

    @removed_parameters(
        RemovedParameter(
            name="width",
            deprecated_in="0.20.31",
            removed_in="2.0",
            hint="use `shape` instead.",
        )
    )
    def __init__(
        self,
        inner: PolarsDataType | PythonDataType,
        shape: int | tuple[int, ...] | None = None,
    ) -> None:
        if shape is None:
            msg = "Array constructor is missing the required argument `shape`"
            raise TypeError(msg)

        inner_parsed = polars.datatypes.parse_into_dtype(inner)
        inner_shape = inner_parsed.shape if isinstance(inner_parsed, Array) else ()

        if isinstance(shape, int):
            self.inner = inner_parsed
            self.size = shape
            self.shape = (shape,) + inner_shape

        elif isinstance(shape, tuple) and isinstance(shape[0], int):  # type: ignore[redundant-expr]
            if len(shape) > 1:
                inner_parsed = Array(inner_parsed, shape[1:])

            self.inner = inner_parsed
            self.size = shape[0]
            self.shape = shape + inner_shape

        else:

View on GitHub (pinned to fe841f959e)