keras-team/keras · error · ValueError

Invalid image1 rank: expected rank 3 (single image) or rank

Error message

Invalid image1 rank: expected rank 3 (single image) or rank 4 (batch of images). Received input with shape: image1.shape={image1.shape}

What it means

compute_output_spec of the SSIM op (keras.ops.image.ssim / SSIM layer) validates image1 is rank 3 (single) or rank 4 (batch). SSIM compares two images structurally, so a non-image-shaped tensor is rejected here first.

Source

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

        self.k1 = k1
        self.k2 = k2
        self.data_format = backend.standardize_data_format(data_format)

    def call(self, image1, image2):
        return _ssim(
            image1,
            image2,
            max_val=self.max_val,
            filter_size=self.filter_size,
            filter_sigma=self.filter_sigma,
            k1=self.k1,
            k2=self.k2,
            data_format=self.data_format,
        )

    def compute_output_spec(self, image1, image2):
        if len(image1.shape) not in (3, 4):
            raise ValueError(
                "Invalid image1 rank: expected rank 3 (single image) "
                "or rank 4 (batch of images). Received input with shape: "
                f"image1.shape={image1.shape}"
            )
        if len(image2.shape) not in (3, 4):
            raise ValueError(
                "Invalid image2 rank: expected rank 3 (single image) "
                "or rank 4 (batch of images). Received input with shape: "
                f"image2.shape={image2.shape}"
            )
        # Output is a scalar per image in the batch
        if len(image1.shape) == 3:
            output_shape = ()
        else:
            output_shape = (image1.shape[0],)
        return KerasTensor(shape=output_shape, dtype=image1.dtype)

View on GitHub (pinned to 7a34a03db6)

Solutions

1. Reshape image1 to (H, W, C) or (N, H, W, C).
2. Check the tensor right before the ssim call, not at model output — intermediate ops may reshape it.
3. Keep both images produced by the same reshape logic so ranks stay equal.

Example fix

# before
ssim(y_pred.reshape(-1, 1024), y_true, 1.0)

# after
ssim(y_pred.reshape(-1, 32, 32, 1), y_true, 1.0)

import numpy as np
a = np.asarray(image1)
if a.ndim == 2: a = a[..., None]
assert a.ndim in (3, 4), a.shape

def is_valid_image_rank(x):
    return getattr(x, 'ndim', None) in (3, 4)

When it happens

Trigger: keras.ops.image.ssim(pred_2d, target_3c, max_val=1.0) with mismatched ranks; passing flattened pixel vectors.

Common situations: Computing SSIM in a custom metric where model output was reshaped to (N, H*W); comparing pre- and post-augmentation images after a squeeze somewhere in the pipeline.

Related errors

• Invalid image2 rank: expected rank 3 (single image) or rank
• Invalid start_points shape: expected (4,2) for a single imag
• Invalid end_points shape: expected (4,2) for a single image
• start_points and end_points must have the same shape. Receiv
• Invalid images rank: expected rank 4 (batch of images). Rece

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