pandas-dev/pandas · error · ValueError

must be block or integer type

Error message

must be block or integer type

What it means

Raised by make_sparse_index when the `kind` argument is neither 'block' nor 'integer'. These are the only two SparseIndex implementations (BlockIndex and IntIndex); any other string corrupts the dispatch and is rejected. The 'pragma: no cover' on the else indicates it is treated as an internal-invariant guard rather than a user-facing path.

Source

Thrown at pandas/core/arrays/sparse/array.py:2166

@overload
def make_sparse_index(length: int, indices, kind: Literal["block"]) -> BlockIndex: ...


@overload
def make_sparse_index(length: int, indices, kind: Literal["integer"]) -> IntIndex: ...


def make_sparse_index(length: int, indices, kind: SparseIndexKind) -> SparseIndex:
    index: SparseIndex
    if kind == "block":
        locs, lens = splib.get_blocks(indices)
        index = BlockIndex(length, locs, lens)
    elif kind == "integer":
        index = IntIndex(length, indices)
    else:  # pragma: no cover
        raise ValueError("must be block or integer type")
    return index

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Use exactly 'block' or 'integer' for kind.
2. Omit kind to accept the default ('integer' is common) when unsure.
3. Validate at the call site: assert kind in {'block','integer'}.

Example fix

// before
sa = pd.arrays.SparseArray([0,1,0], kind='int')  # raises 'must be block or integer'

// after
sa = pd.arrays.SparseArray([0,1,0], kind='integer')

import pandas as pd

def make_sparse_safe(values, kind='integer', fill_value=None):
    if kind not in {'block', 'integer'}:
        raise ValueError("kind must be 'block' or 'integer'")
    return pd.arrays.SparseArray(values, kind=kind, fill_value=fill_value)

def is_valid_sparse_kind(kind) -> bool:
    return kind in {'block', 'integer'}

try:
    sa = pd.arrays.SparseArray(values, kind=kind)
except ValueError as e:
    if 'block or integer' in str(e):
        sa = pd.arrays.SparseArray(values, kind='integer')
    else:
        raise

When it happens

Trigger: Constructing a SparseArray with kind='dense', kind=None, or a typo like kind='int'. User-facing exposure is via SparseArray(..., kind=...) and SparseDtype(..., kind=...).

Common situations: Typing the kind argument, passing a variable that was supposed to be 'integer'/'block' but is None, or copying code from an older pandas version that accepted different spellings.

Related errors

• Inferred frequency {inferred} from passed values does not co
• periods must be an integer, got {periods}
• Passed data is timezone-aware, incompatible with 'tz=None'.
• Must provide freq argument if no data is supplied
• Of the four parameters: start, end, periods, and freq, exact

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