pandas-dev/pandas · error · TypeError

Input must be list-like

Error message

Input must be list-like

What it means

Raised by factorize_from_iterables (the internal factorize helper) when the input values are not list-like. The function expects an iterable (list, array, Series, Index, etc.); a scalar (str, int, None) is rejected with TypeError. This guard mirrors np.array/list semantics where scalar inputs would produce wrong codes.

Source

Thrown at pandas/core/arrays/categorical.py:3217

    """
    Factorize an input `values` into `categories` and `codes`. Preserves
    categorical dtype in `categories`.

    Parameters
    ----------
    values : list-like

    Returns
    -------
    codes : ndarray
    categories : Index
        If `values` has a categorical dtype, then `categories` is
        a CategoricalIndex keeping the categories and order of `values`.
    """
    from pandas import CategoricalIndex

    if not is_list_like(values):
        raise TypeError("Input must be list-like")

    categories: Index

    vdtype = getattr(values, "dtype", None)
    if isinstance(vdtype, CategoricalDtype):
        values = extract_array(values)
        # The Categorical we want to build has the same categories
        # as values but its codes are by def [0, ..., len(n_categories) - 1]
        cat_codes = np.arange(len(values.categories), dtype=values.codes.dtype)
        cat = Categorical.from_codes(cat_codes, dtype=values.dtype, validate=False)

        categories = CategoricalIndex(cat)
        codes = values.codes
    else:
        # The value of ordered is irrelevant since we don't use cat as such,
        # but only the resulting categories, the order of which is independent
        # from ordered. Set ordered to False as default. See GH #15457
        cat = Categorical(values, ordered=False)

View on GitHub (pinned to 71959b8cb9)

Solutions

  1. Wrap the scalar in a list: pd.factorize([value]) instead of pd.factorize(value).
  2. Verify the input is a list/array/Series before calling; use isinstance(x, (list, tuple, pd.Series, np.ndarray)).
  3. Check the calling pandas API's expected input shape in its docstring.

Example fix

// before
pd.factorize('a')  # TypeError: Input must be list-like

// after
pd.factorize(['a','a','b'])
Defensive patterns

Strategy: validation

Validate before calling

import pandas as pd
def ensure_list_like(v):
    if not pd.api.types.is_list_like(v):
        return [v]
    return v

Type guard

import pandas as pd
from typing import Any

def is_list_like(v: Any) -> bool:
    return pd.api.types.is_list_like(v)

Try / catch

try:
    pd.factorize(value)
except TypeError as e:
    if 'Input must be list-like' in str(e):
        pd.factorize([value])
    else:
        raise

Prevention

When it happens

Trigger: Calling pd.factorize('a'), pd.Categorical.from_codes on a scalar input, groupby on a scalar key, or passing a scalar where pandas internally calls factorize_from_iterable (e.g. MultiIndex construction, pivot internals).

Common situations: User code that passes a single string or number where a list-like is required; programmatic callers that did not wrap scalar values in a list.

Related errors

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