huggingface/transformers · error · ValueError

Conv3dToLinear expects a 5D or 2D tensor, got {tensor.ndim}D

Error message

Conv3dToLinear expects a 5D or 2D tensor, got {tensor.ndim}D

What it means

Raised by Conv3dToLinear.convert (core_model_loading.py:379). This op converts a Conv3d weight (5D: [out_ch, in_ch, kH, kW, kD]) into a flattened Linear weight (2D) by merging the last four axes. If the collected tensor is neither 5D nor already 2D (e.g. it is 4D because the checkpoint stores a Conv2d weight, or 1D because a bias was matched), the reshape is ambiguous and the op refuses to proceed.

Source

Thrown at src/transformers/core_model_loading.py:379

        if len(target_patterns) > 1:
            if len(source_patterns) == 1:
                return source_patterns[0]
            else:
                raise ValueError("Undefined Operation encountered!")
        return target_patterns[0]

    @torch.no_grad
    def convert(
        self, input_dict: dict[str, torch.Tensor], source_patterns: list[str], target_patterns: list[str], **kwargs
    ) -> dict[str, torch.Tensor]:
        target_pattern = self._get_target_pattern(input_dict, source_patterns, target_patterns)
        tensors = next(iter(input_dict.values()))
        tensor = tensors[0] if isinstance(tensors, list) else tensors

        if tensor.ndim == 5:
            tensor = tensor.reshape(tensor.shape[0], -1).contiguous()
        elif tensor.ndim != 2:
            raise ValueError(f"Conv3dToLinear expects a 5D or 2D tensor, got {tensor.ndim}D")

        return {target_pattern: tensor}

    @property
    def reverse_op(self) -> ConversionOps:
        return LinearToConv3d(in_channels=self.in_channels, kernel_size=self.kernel_size)


class LinearToConv3d(ConversionOps):
    """Flattened Linear weights → Conv3d layout."""

    def __init__(self, in_channels: int, kernel_size: tuple[int, int, int]):
        self.in_channels = in_channels
        self.kernel_size = kernel_size

    @torch.no_grad
    def convert(
        self, input_dict: dict[str, torch.Tensor], source_patterns: list[str], target_patterns: list[str], **kwargs

View on GitHub (pinned to a597f97485)

Solutions

1. Inspect the ndim/shape of the tensor collected for the failing pattern and tighten source_patterns so only the intended Conv3d weight matches.
2. If the checkpoint really stores a 4D Conv2d weight, use Conv2dToLinear (or the appropriate op) instead of Conv3dToLinear.
3. If the tensor is already a 2D Linear weight, the op passes it through — verify you are not double-converting or wrapping the tensor in an extra list dimension.
4. Check for a mismatch between the checkpoint revision and the conversion recipe version (old recipes vs new checkpoints).

Example fix

# before: broad pattern matches a 4D conv2d weight
WeightConverter(source_patterns=[r"vision.*weight"], target_patterns=[r"vision.fc.weight"], operations=[Conv3dToLinear()])

# after: pattern anchored to the actual conv3d block
WeightConverter(source_patterns=[r"vision.blocks.*conv3d.weight"], target_patterns=[r"vision.fc.weight"], operations=[Conv3dToLinear()])

matched = [k for k in state_dict if re.search(pattern, k)]
for k in matched:
    nd = state_dict[k].ndim
    assert nd in (5, 2), f'{k} has ndim={nd}; Conv3dToLinear needs 5D or 2D — check the op or tighten the pattern'

def is_conv3d_or_linear_weight(t: "torch.Tensor") -> bool:
    return t.ndim in (5, 2)

When it happens

Trigger: A WeightConverter with operations=[Conv3dToLinear()] whose source pattern matches a tensor with ndim not in {5, 2}: typically a Conv2d weight (4D), a bias (1D), or a BatchNorm/LayerNorm parameter matched by an overly broad regex such as '.*weight' instead of '.*conv.*weight'.

Common situations: Porting a 3D-vision or video model (e.g. video encoders in VLMs) where the original repo used Conv3d but the checkpoint has an extra/fewer axis than expected; or the source regex accidentally matches unrelated weights. Also happens after upstream changes a Conv3d to Conv2d.

Related errors

• Cannot reshape tensor with shape {tensor.shape} into {target
• Failed to convert {kwargs.get('full_layer_name')}
• PermuteForRope expects a single tensor per key.
• Expected pattern {key} in collected tensors but only found t
• `num_head` was provided as a list of length {len(num_heads)}

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/71e430800877635d. Report an issue: GitHub.