matplotlib/matplotlib · error · ValueError

The shapes of 'flows' {np.shape(flows)} and 'orientations' {

Error message

The shapes of 'flows' {np.shape(flows)} and 'orientations' {np.shape(orientations)} are incompatible

What it means

In Sankey.add(), 'orientations' (values -1/0/1 saying whether each flow goes to the bottom, right/left, or top) is normalized with np.broadcast_to(orientations, n) where n = len(flows). A scalar broadcasts to all flows, but an array whose length is neither 1 nor n fails the broadcast, and sankey.py:447-452 re-raises that failure as a ValueError naming the two shapes. So the error means your orientations list has a different length than your flows list.

Source

Thrown at lib/matplotlib/sankey.py:449

        See Also
        --------
        Sankey.finish
        """
        # Check and preprocess the arguments.
        flows = np.array([1.0, -1.0]) if flows is None else np.array(flows)
        n = flows.shape[0]  # Number of flows
        if rotation is None:
            rotation = 0
        else:
            # In the code below, angles are expressed in deg/90.
            rotation /= 90.0
        if orientations is None:
            orientations = 0
        try:
            orientations = np.broadcast_to(orientations, n)
        except ValueError:
            raise ValueError(
                f"The shapes of 'flows' {np.shape(flows)} and 'orientations' "
                f"{np.shape(orientations)} are incompatible"
            ) from None
        try:
            labels = np.broadcast_to(labels, n)
        except ValueError:
            raise ValueError(
                f"The shapes of 'flows' {np.shape(flows)} and 'labels' "
                f"{np.shape(labels)} are incompatible"
            ) from None
        if trunklength < 0:
            raise ValueError(
                "'trunklength' is negative, which is not allowed because it "
                "would cause poor layout")
        if abs(np.sum(flows)) > self.tolerance:
            _log.info("The sum of the flows is nonzero (%f; patchlabel=%r); "
                      "is the system not at steady state?",
                      np.sum(flows), patchlabel)

View on GitHub (pinned to b379c1b69e)

Solutions

Make len(orientations) == len(flows), with each entry in {-1, 0, 1}.
If all flows share one orientation, pass a scalar (orientations=1) and let broadcasting apply it.
Build both lists from the same source rows so they cannot diverge (e.g. zip one DataFrame iteration).

Example fix

# before
sankey.add(flows=[1, -1, 0.5], orientations=[1, -1])

# after
sankey.add(flows=[1, -1, 0.5], orientations=[1, -1, 0])
# or all the same: sankey.add(flows=[1, -1, 0.5], orientations=1)

Defensive patterns

Strategy: validation

Validate before calling

import numpy as np

def check_add_shapes(flows, orientations, labels):
    n = len(flows)
    if np.size(orientations) not in (1, n):
        raise ValueError(f'orientations has {np.size(orientations)} entries, flows has {n}')
    if np.size(labels) not in (1, n):
        raise ValueError(f'labels has {np.size(labels)} entries, flows has {n}')

check_add_shapes(flows, orientations, labels)
sankey.add(flows=flows, orientations=orientations, labels=labels)

Try / catch

try:
    sankey.add(flows=flows, orientations=orientations)
except ValueError as e:
    if 'incompatible' in str(e):
        # log shapes to find the diverging source
        raise ValueError(f'{e}; flows={np.shape(flows)}') from None
    raise

Prevention

Derive flows, orientations, and labels from the same row iteration so they stay aligned.
Prefer a scalar orientations value when all flows share a direction.
Add a shape-check helper in test suites for data-pipeline code feeding Sankey.

When it happens

Trigger: sankey.add(flows=[1, -1, 0.5], orientations=[1, -1]) — 3 flows, 2 orientations; passing orientations as a 2-D array like [[1, -1]]; adding or removing a flow value without updating the orientations list.

Common situations: Editing a data-driven flows list (e.g. from a DataFrame column) while orientations stays hard-coded; passing df['direction'].tolist() where the DataFrame was filtered independently of the flows column.

Related errors

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