pandas-dev/pandas · error · TypeError

values must be a 1D list-like

Error message

values must be a 1D list-like

What it means

Raised by _coerce_to_data_and_mask when values.ndim != 1. NumericArray (and all BaseMaskedArray subclasses) are strictly 1-D; passing a 2-D array or higher is rejected because the mask and data buffers must be 1-D aligned.

Source

Thrown at pandas/core/arrays/numeric.py:188

        if inferred_type == "boolean" and dtype is None:
            # object dtype array of bools
            name = dtype_cls.__name__.strip("_")
            raise TypeError(f"{values.dtype} cannot be converted to {name}")

    elif values.dtype.kind == "b" and checker(dtype):
        # fastpath
        mask = np.zeros(len(values), dtype=np.bool_)
        if not copy:
            values = np.asarray(values, dtype=default_dtype)
        else:
            values = np.array(values, dtype=default_dtype, copy=copy)

    elif values.dtype.kind not in "iuf":
        name = dtype_cls.__name__.strip("_")
        raise TypeError(f"{values.dtype} cannot be converted to {name}")

    if values.ndim != 1:
        raise TypeError("values must be a 1D list-like")

    if mask is None:
        if values.dtype.kind in "iu":
            # fastpath
            mask = np.zeros(len(values), dtype=np.bool_)
        elif values.dtype.kind == "f":
            # np.isnan is faster than is_numeric_na() for floats
            # github issue: #60066
            if is_nan_na():
                mask = np.isnan(values)
            else:
                mask = np.zeros(len(values), dtype=np.bool_)
                if dtype_cls.__name__.strip("_").startswith(("I", "U")):
                    wrong = np.isnan(values)
                    if wrong.any():
                        raise ValueError("Cannot cast NaN value to Integer dtype.")
        elif is_nan_na():
            mask = libmissing.is_numeric_na(values)

View on GitHub (pinned to 71959b8cb9)

Solutions

  1. Select a single column / flatten: pd.array(matrix[:, 0], dtype='Int64').
  2. Construct one masked array per column and assemble into a DataFrame.
  3. Use df = pd.DataFrame(matrix, dtype='Int64') for columnwise conversion.

Example fix

// before
pd.array(np.array([[1, 2], [3, 4]]), dtype="Int64")  # raises: values must be a 1D list-like

// after
pd.array(np.array([[1, 2], [3, 4]])[:, 0], dtype="Int64")
Defensive patterns

Strategy: validation

Validate before calling

import numpy as np

def ensure_1d_values(values):
    arr = np.asarray(values)
    if arr.ndim != 1:
        raise TypeError(f"values must be 1D, got ndim={arr.ndim}")
    return arr

Type guard

def is_1d(values) -> bool:
    import numpy as np
    return np.asarray(values).ndim == 1

Try / catch

try:
    arr = pd.array(values, dtype="Int64")
except TypeError as e:
    if "1D list-like" in str(e):
        arr = pd.array(np.asarray(values)[:, 0], dtype="Int64")
    else:
        raise

Prevention

When it happens

Trigger: pd.array(matrix, dtype='Int64') or IntegerArray(...) with a 2-D numpy array / nested list-like that asarray converts to ndim>=2.

Common situations: Passing a DataFrame.values or np.ndarray of shape (n,m) where a 1-D column was expected; nested lists interpreted as 2-D.

Related errors

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/11fba0d7f7c57064. Report an issue: GitHub.