{"record":{"id":"dd56562382ce1670","repo":"matplotlib/matplotlib","slug":"alpha-is-array-like-but-its-shape-alpha-shape-do","errorCode":null,"errorMessage":"alpha is array-like but its shape {alpha.shape} does not match that of X {xa.shape}","messagePattern":"alpha is array-like but its shape (.+?) does not match that of X (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"lib/matplotlib/colors.py","lineNumber":851,"sourceCode":"        with np.errstate(invalid=\"ignore\"):\n            # We need this cast for unsigned ints as well as floats\n            xa = xa.astype(int)\n        xa[mask_under] = self._i_under\n        xa[mask_over] = self._i_over\n        xa[mask_bad] = self._i_bad\n\n        lut = self._lut\n        if bytes:\n            lut = (lut * 255).astype(np.uint8)\n\n        rgba = lut.take(xa, axis=0, mode='clip')\n\n        if alpha is not None:\n            alpha = np.clip(alpha, 0, 1)\n            if bytes:\n                alpha *= 255  # Will be cast to uint8 upon assignment.\n            if alpha.shape not in [(), xa.shape]:\n                raise ValueError(\n                    f\"alpha is array-like but its shape {alpha.shape} does \"\n                    f\"not match that of X {xa.shape}\")\n            rgba[..., -1] = alpha\n            # If the \"bad\" color is all zeros, then ignore alpha input.\n            if (lut[-1] == 0).all():\n                rgba[mask_bad] = (0, 0, 0, 0)\n\n        return rgba, mask_bad\n\n    def __copy__(self):\n        cls = self.__class__\n        cmapobject = cls.__new__(cls)\n        cmapobject.__dict__.update(self.__dict__)\n        if self._isinit:\n            cmapobject._lut = np.copy(self._lut)\n        return cmapobject\n\n    def __eq__(self, other):","sourceCodeStart":833,"sourceCodeEnd":869,"githubUrl":"https://github.com/matplotlib/matplotlib/blob/b379c1b69e012b142c0f496a52bcb30513802d72/lib/matplotlib/colors.py#L833-L869","documentation":"When a Colormap is called with an array-like alpha (cmap(X, alpha=...)), the alpha must be a scalar or an array whose shape exactly equals the shape of the normalized data X. Any other shape is rejected before the alpha channel is written into the RGBA output.","triggerScenarios":"cmap(xa, alpha=np.ones((n, 1))) when xa has shape (n,); an (h, w) per-pixel alpha applied to 1D scatter data; an alpha list converted to a shape that differs from X.","commonSituations":"Reusing per-pixel opacity masks computed for a 2D image with 1D data; arrays reshaped or raveled between alpha computation and the colormap call; assuming length equality is enough.","solutions":["Reshape alpha to match the data: cmap(x, alpha=alpha.reshape(x.shape)) or np.broadcast_to(alpha, x.shape).","Pass a scalar alpha when uniform transparency is wanted.","Assert the shape before the call: alpha.shape in ((), x.shape)."],"exampleFix":"// before\nrgba = cmap(xa, alpha=alpha_2d)  # alpha_2d.shape == (n, 1), xa.shape == (n,)\n// after\nrgba = cmap(xa, alpha=alpha_2d.reshape(-1))","handlingStrategy":"validation","validationCode":"import numpy as np\n\ndef conform_alpha(alpha, xa):\n    if alpha is None or np.ndim(alpha) == 0:\n        return alpha\n    alpha = np.asarray(alpha, dtype=float)\n    if alpha.shape == ():\n        return float(alpha)\n    if alpha.shape != xa.shape and alpha.size == xa.size:\n        alpha = alpha.reshape(xa.shape)\n    return alpha","typeGuard":null,"tryCatchPattern":"try:\n    rgba = cmap(xa, alpha=alpha)\nexcept ValueError as e:\n    if 'does not match that of X' in str(e):\n        rgba = cmap(xa, alpha=np.broadcast_to(alpha, xa.shape))\n    else:\n        raise","preventionTips":["Keep alpha and data arrays in one shape throughout the plotting pipeline.","Prefer scalar alpha unless per-point transparency is required.","Reshape alpha at the call site: cmap(x, alpha=alpha.reshape(x.shape))."],"tags":["matplotlib","colormap","alpha","shape-mismatch"],"backgroundTag":"alpha-shape-mismatch","analyzedSha":"b379c1b69e012b142c0f496a52bcb30513802d72","analyzedAt":"2026-08-21T23:31:55.468Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}