keras-team/keras · error · ValueError

`patches` has unexpected rank for 3D channels_first reconstr

Error message

`patches` has unexpected rank for 3D channels_first reconstruction. Expected 4 (unbatched) or 5 (batched). Received shape: {patches.shape}

What it means

For data_format='channels_first', 3D reconstruct_patches first transposes your patches from (flat, gD, gH, gW) or (B, flat, gD, gH, gW) into channels-last layout. If patches has any other rank (e.g. you already passed channels-last rank-5 patches together with channels_first), the transpose is impossible and it raises.

Source

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

        raise ValueError(
            "Invalid `output_size`. Expected length 3 (D, H, W). "
            f"Got: output_size={output_size}"
        )
    if padding not in ("same", "valid"):
        raise ValueError(
            f"Invalid `padding`. Expected 'same' or 'valid'. Got: {padding}"
        )
    _validate_reconstruct_strides(size, strides, "reconstruct_patches")
    data_format = backend.standardize_data_format(data_format)
    if data_format == "channels_first":
        # Reconstruct in channels_last layout, then move channels back.
        # Patches are (flat, gD, gH, gW) unbatched or (B, flat, gD, gH, gW).
        if len(patches.shape) == 4:
            patches = backend.numpy.transpose(patches, axes=(1, 2, 3, 0))
        elif len(patches.shape) == 5:
            patches = backend.numpy.transpose(patches, axes=(0, 2, 3, 4, 1))
        else:
            raise ValueError(
                "`patches` has unexpected rank for 3D channels_first "
                "reconstruction. Expected 4 (unbatched) or 5 (batched). "
                f"Received shape: {patches.shape}"
            )
        result = _reconstruct_patches_3d(
            patches, size, output_size, strides, padding, "channels_last"
        )
        if len(result.shape) == 4:
            return backend.numpy.transpose(result, axes=(3, 0, 1, 2))
        return backend.numpy.transpose(result, axes=(0, 4, 1, 2, 3))

    pD, pH, pW = size
    D, H, W = output_size

    if len(patches.shape) not in (4, 5):
        raise ValueError(
            "`patches` has unexpected rank for 3D reconstruction. "
            "Expected 4 (unbatched) or 5 (batched). "

View on GitHub (pinned to 7a34a03db6)

Solutions

1. Feed the same layout extract_patches produced: flat-dim-first (rank 4 unbatched / rank 5 batched) when using channels_first
2. Or drop data_format (use channels_last) and pass (B,gD,gH,gW,C) patches
3. Check len(patches.shape) before the call

Example fix

# before
reconstruct_patches(patches_cl, size, out, data_format='channels_first')
# patches_cl has shape (B, gD, gH, gW, C)

# after
reconstruct_patches(patches_cl, size, out)  # channels_last default

if data_format == 'channels_first':
    assert len(patches.shape) in (4, 5), 'need (flat,gD,gH,gW) or (B,flat,gD,gH,gW)'

def channels_first_3d_ok(patches) -> bool:
    return len(patches.shape) in (4, 5)

When it happens

Trigger: reconstruct_patches(patches, ..., data_format='channels_first') with patches of rank 3 or 6, or with channels-last style (B,gD,gH,gW,C) rank-5 patches.

Common situations: Mixing layout conventions between extract and reconstruct; passing patches already transposed; loading patches saved in channels_last while the model config says channels_first.

Related errors

• `patches` has unexpected rank for 3D reconstruction. Expecte
• For `padding='same'`, `output_size` width ({W}) must be in t
• `padding='valid'` requires output_size to equal size * grid.
• Invalid `output_size`. Expected length 3 (D, H, W). Got: out
• `patches` last dim ({static_flat}) is not divisible by prod(

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