keras-team/keras · error · ValueError

Invalid images rank: expected rank 4 (batch of images). Rece

Error message

Invalid images rank: expected rank 4 (batch of images). Received: images.shape={images_shape}

What it means

sobel_edges strictly requires a rank-4 batched tensor (N, H, W, C); unlike other image ops it rejects single rank-3 images. compute_output_spec appends a trailing size-2 axis for [dy, dx], which only makes sense for a batch.

Source

Thrown at keras/src/ops/image.py:2635

        translation,
        spatial_dims,
        method,
        antialias,
    )


class SobelEdges(Operation):
    def __init__(self, data_format=None, *, name=None):
        super().__init__(name=name)
        self.data_format = backend.standardize_data_format(data_format)

    def call(self, images):
        return backend.image.sobel_edges(images, data_format=self.data_format)

    def compute_output_spec(self, images):
        images_shape = list(images.shape)
        if len(images_shape) != 4:
            raise ValueError(
                "Invalid images rank: expected rank 4 (batch of images). "
                f"Received: images.shape={images_shape}"
            )
        # Output adds an extra dimension of size 2 for [dy, dx]
        output_shape = images_shape + [2]
        return KerasTensor(shape=output_shape, dtype=images.dtype)


@keras_export("keras.ops.image.sobel_edges")
def sobel_edges(images, data_format=None):
    """Computes Sobel edge detection on images.

    The Sobel operator computes the gradient of the image intensity at each
    pixel, giving the direction of the largest increase from light to dark
    and the rate of change in that direction.

    Args:
        images: Input tensor of shape `(batch, height, width, channels)` if

View on GitHub (pinned to 7a34a03db6)

Solutions

Expand a single image to a batch: images[None, ...].
For (N, H, W) grayscale, add the channel axis too: images[..., None].
Remember the output is (N, H, W, C, 2).

Example fix

# before
edges = keras.ops.image.sobel_edges(img)  # img: (H, W, C)

# after
edges = keras.ops.image.sobel_edges(img[None])[0]

Defensive patterns

Strategy: validation

Validate before calling

import numpy as np
x = np.asarray(images)
if x.ndim == 3: x = x[np.newaxis]
assert x.ndim == 4, x.shape

Type guard

def is_batched_nhwc(x):
    return getattr(x, 'ndim', None) == 4

Prevention

Remember sobel_edges is batch-only, unlike most keras.image ops.
Wrap the op in a layer that adds the batch axis once.

When it happens

Trigger: keras.ops.image.sobel_edges(single_image) with shape (H, W, C); passing (N, H, W) grayscale without channel or batch axes.

Common situations: Applying Sobel inside a per-example loop; feeding grayscale stored as (H, W) after squeeze; assuming rank-3 support because sibling ops allow it.

Related errors

AI-assisted analysis of keras-team/keras@7a34a03db6 (2026-08-25). Data as JSON: /api/errors/79f1e999ebb01b73. Report an issue: GitHub.