roboflow/supervision · error · ValueError

Blur kernel dimensions must be positive

Error message

Blur kernel dimensions must be positive

What it means

The fallback cv2.blur runs scipy.ndimage.uniform_filter, which requires positive kernel extents in both axes. A ksize containing 0 or a negative value would make the filter undefined, so it is rejected before the scipy call.

Source

Thrown at src/supervision/_cv2/_transform.py:18

"""Private transform and filter fallbacks."""

from __future__ import annotations

from typing import Any

import numpy as np
import numpy.typing as npt

from supervision._cv2._common import _cast_array_like_opencv


def _blur(
    image: npt.NDArray[Any], ksize: tuple[int, int], border_type: int = 4
) -> npt.NDArray[Any]:
    """Apply a box filter with OpenCV's default reflect-101 boundary behavior."""
    if min(ksize) <= 0:
        raise ValueError("Blur kernel dimensions must be positive")
    if border_type != 4:
        raise ValueError("Only OpenCV's default blur border is supported")

    from scipy import ndimage

    size = (*ksize[::-1], 1) if image.ndim == 3 else ksize[::-1]
    values = ndimage.uniform_filter(image.astype(np.float64), size=size, mode="mirror")
    return np.ascontiguousarray(_cast_array_like_opencv(values, image.dtype))

View on GitHub (pinned to 7f254d9784)

Solutions

1. Skip the blur entirely when the configured strength is 0 instead of calling cv2.blur with a zero kernel.
2. Ensure ksize entries are >= 1; use max(1, k) if a computed size can round down to 0.
3. Validate kernel parameters at the API/config boundary.

Example fix

# before
blurred = cv2.blur(frame, (blur_ksize, blur_ksize))  # blur_ksize may be 0

# after
blurred = cv2.blur(frame, (blur_ksize, blur_ksize)) if blur_ksize > 0 else frame

if min(ksize) <= 0:
    raise ValueError(f'blur kernel must be positive: {ksize}')
blurred = cv2.blur(image, ksize)

When it happens

Trigger: cv2.blur(image, (0, 5)), negative kernel sizes, or ksize computed from a parameter that defaults to 0 when not configured.

Common situations: Config-driven blur strength where 0 means 'disabled' but the call is still made; odd/even kernel math producing 0 for tiny inputs; unvalidated user parameters.

Related errors

• Resize dimensions must be positive
• Unsupported flip code: {flip_code}
• epsilon must be non-negative
• Only OpenCV's default blur border is supported
• Connected-component input must be a two-dimensional image

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/7b8a6feb0084d525. Report an issue: GitHub.