{"record":{"id":"d12b81aecbc5e55a","repo":"jax-ml/jax","slug":"convolve2d-only-supports-2-dimensional-inputs","errorCode":null,"errorMessage":"convolve2d() only supports 2-dimensional inputs.","messagePattern":"convolve2d\\(\\) only supports 2-dimensional inputs\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/scipy/signal.py","lineNumber":327,"sourceCode":"\n    Specifying ``mode = 'same'`` returns a centered 2D convolution of the same size\n    as the first input:\n\n    >>> jax.scipy.signal.convolve2d(x, y, mode='same')\n    Array([[22., 17.],\n           [30., 32.]], dtype=float32)\n\n    Specifying ``mode = 'valid'`` returns only the portion of 2D convolution\n    where the two arrays fully overlap:\n\n    >>> jax.scipy.signal.convolve2d(x, y, mode='valid')\n    Array([[22., 17.],\n           [30., 32.]], dtype=float32)\n  \"\"\"\n  if boundary != 'fill' or fillvalue != 0:\n    raise NotImplementedError(\"convolve2d() only supports boundary='fill', fillvalue=0\")\n  if np.ndim(in1) != 2 or np.ndim(in2) != 2:\n    raise ValueError(\"convolve2d() only supports 2-dimensional inputs.\")\n  return _convolve_nd(in1, in2, mode, precision=precision)\n\n\ndef correlate(in1: Array, in2: Array, mode: ModeString = 'full', method: str = 'auto',\n              precision: PrecisionLike = None) -> Array:\n  \"\"\"Cross-correlation of two N-dimensional arrays.\n\n  JAX implementation of :func:`scipy.signal.correlate`.\n\n  Args:\n    in1: left-hand input to the cross-correlation.\n    in2: right-hand input to the cross-correlation. Must have ``in1.ndim == in2.ndim``.\n    mode: controls the size of the output. Available operations are:\n\n      * ``\"full\"``: (default) output the full cross-correlation of the inputs.\n      * ``\"same\"``: return a centered portion of the ``\"full\"`` output which\n        is the same size as ``in1``.\n      * ``\"valid\"``: return the portion of the ``\"full\"`` output which do not","sourceCodeStart":309,"sourceCodeEnd":345,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/scipy/signal.py#L309-L345","documentation":"convolve2d requires both inputs to be exactly 2-D; it is a thin wrapper over the N-D _convolve_nd but validates rank to match the SciPy 2-D API contract. Higher- or lower-rank arrays raise this.","triggerScenarios":"Passing a batched (N,H,W) tensor, a 1-D vector, or a scalar alongside a 2-D kernel to jax.scipy.signal.convolve2d.","commonSituations":"Adding a batch dimension for vmap/jit pipelines then forgetting to drop it before calling convolve2d; using convolve2d where convolve (N-D) was intended.","solutions":["Use jax.scipy.signal.convolve for N-D inputs (it supports any matching rank)","squeeze extra axes: convolve2d(x[0], k) for batched data, or vmap over the batch","Reshape 1-D inputs to (1, n) or (n, 1) if 2-D semantics are wanted"],"exampleFix":"// before\ny = jax.scipy.signal.convolve2d(batched_x, k)  # batched_x: (8,H,W)\n// after\ny = jax.vmap(lambda im: jax.scipy.signal.convolve2d(im, k))(batched_x)","handlingStrategy":"validation","validationCode":"assert np.ndim(in1) == 2 and np.ndim(in2) == 2, 'convolve2d needs 2-D inputs'","typeGuard":"def is_2d(a) -> bool:\n    return jnp.asarray(a).ndim == 2","tryCatchPattern":null,"preventionTips":["Use jax.scipy.signal.convolve for N-D work","vmap over batch axes instead of passing batched arrays"],"tags":["jax","scipy","convolution","rank-mismatch","shape-validation"],"backgroundTag":"wrong-dimensionality-input","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}