matplotlib/matplotlib · error · ValueError

For a `BivarColormap` the data must have a first dimension 2

Error message

For a `BivarColormap` the data must have a first dimension 2, not {len(X)}

What it means

BivarColormap maps exactly two data arrays: X must be a sequence with first dimension 2 (for example [X0, X1]). Any other first-dimension length is rejected before the normalization and color mixing run.

Source

Thrown at lib/matplotlib/colors.py:1766

            - For integers, *X* should be in the interval ``[0, Colormap.N)`` to
              return RGBA values *indexed* from the Colormap with index ``X``.

        alpha : float or array-like or None, default: None
            Alpha must be a scalar between 0 and 1, a sequence of such
            floats with shape matching X0, or None.
        bytes : bool, default: False
            If False (default), the returned RGBA values will be floats in the
            interval ``[0, 1]`` otherwise they will be `numpy.uint8`\s in the
            interval ``[0, 255]``.

        Returns
        -------
        Tuple of RGBA values if X is scalar, otherwise an array of
        RGBA values with a shape of ``X.shape + (4, )``.
        """

        if len(X) != 2:
            raise ValueError(
                f'For a `BivarColormap` the data must have a first dimension '
                f'2, not {len(X)}')

        if not self._isinit:
            self._init()

        X0 = np.ma.array(X[0], copy=True)
        X1 = np.ma.array(X[1], copy=True)
        # clip to shape of colormap, circle square, etc.
        self._clip((X0, X1))

        # Native byteorder is faster.
        if not X0.dtype.isnative:
            X0 = X0.byteswap().view(X0.dtype.newbyteorder())
        if not X1.dtype.isnative:
            X1 = X1.byteswap().view(X1.dtype.newbyteorder())

        if X0.dtype.kind == "f":

View on GitHub (pinned to b379c1b69e)

Solutions

Pass two arrays: rgba = bivar_cmap([X0, X1]).
If the data is a stacked array, make its shape (2, ...) first: np.stack([X0, X1]) or transpose as needed.
For three or more variates, use MultivarColormap instead of BivarColormap.

Example fix

// before
rgba = bivar_cmap(X0)  # only one array
// after
rgba = bivar_cmap([X0, X1])

Defensive patterns

Strategy: validation

Validate before calling

import numpy as np

def conform_bivar(X):
    if np.asarray(X).shape[0] != 2:
        raise ValueError(
            'BivarColormap needs exactly 2 data arrays, e.g. [X0, X1]')
    return X

Try / catch

try:
    rgba = bivar_cmap(X)
except ValueError as e:
    if 'first dimension 2' in str(e):
        raise ValueError('pass [X0, X1] to BivarColormap') from e
    raise

Prevention

Wrap the two variates in a list at the call site.
Keep bivariate data stacks in (2, H, W) shape.
Use MultivarColormap for more than two variates.

When it happens

Trigger: bivar_cmap(X0) with the list wrapper missing; bivar_cmap([X0, X1, X2]) with three arrays; passing a channels-last stack (H, W, 2) whose first dimension is H.

Common situations: Feeding an array stacked for another imaging API that puts channels last; leftover code written for 3+ variates; forgetting the list wrapper when both variates come from one variable.

Related errors

AI-assisted analysis of matplotlib/matplotlib@b379c1b69e (2026-08-21). Data as JSON: /api/errors/570393708c002a56. Report an issue: GitHub.