huggingface/transformers · error · ValueError

Failed to convert {kwargs.get('full_layer_name')}

Error message

Failed to convert {kwargs.get('full_layer_name')}

What it means

Raised by the Chunk conversion op during checkpoint weight conversion (core_model_loading.py:130). Chunk splits one collected tensor along `dim` into exactly len(target_patterns) pieces; the error fires when more than one source pattern was collected, when there is only one target pattern (nothing to split), or when torch.chunk did not produce one chunk per target (the tensor's size along `dim` is not divisible into that many chunks). The layer name is included via kwargs['full_layer_name'] so you can locate the offending weight in the conversion recipe.

Source

Thrown at src/transformers/core_model_loading.py:130

class Chunk(ConversionOps):
    """Split a tensor along `dim` into equally sized chunks."""

    def __init__(self, dim: int = 0):
        self.dim = dim

    @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]:
        tensors = next(iter(input_dict.values()))
        tensor = tensors[0] if isinstance(tensors, list) else tensors
        targets = target_patterns
        sizes = len(targets)
        chunks = tuple(chunk.contiguous() for chunk in torch.chunk(tensor, sizes, dim=self.dim))
        if len(input_dict) > 1 or len(target_patterns) == 1 or len(chunks) != len(target_patterns):
            raise ValueError(f"Failed to convert {kwargs.get('full_layer_name')}")
        return dict(zip(targets, chunks))

    @property
    def reverse_op(self) -> ConversionOps:
        return Concatenate(self.dim)


class Concatenate(ConversionOps):
    """Concatenate tensors along `dim`."""

    def __init__(self, dim: int = 0):
        self.dim = dim

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

View on GitHub (pinned to a597f97485)

Solutions

1. Print the collected keys and the tensor shape for the failing layer (wrap convert or inspect the checkpoint state dict) and compare tensor.shape[dim] against len(target_patterns).
2. Fix target_patterns so its length equals the number of chunks actually present (e.g. 3 for q/k/v, 2 for gate/up) and ensure the source pattern matches exactly ONE checkpoint key.
3. If the tensor's dim is not divisible by the number of targets, switch to an op that splits by explicit sizes or fix the dim argument (e.g. Chunk(dim=0) vs Chunk(dim=1)).
4. If you genuinely have multiple source tensors to fuse first, chain Concatenate before Chunk or use a many-to-many capable internal op.

Example fix

# before: fused tensor has shape [2*hidden, ...] but 3 targets declared
WeightConverter(source_patterns=[r"layers\..*\.attn.fused"], target_patterns=[r"q_proj", r"k_proj", r"v_proj"], operations=[Chunk(dim=0)])

# after: fused tensor only holds q,k (2 chunks) -> match target count to the real arity
WeightConverter(source_patterns=[r"layers\..*\.attn\.fused"], target_patterns=[r"q_proj", r"k_proj"], operations=[Chunk(dim=0)])

def check_chunk convertible(transform, state_dict):
    src = transform.source_patterns
    keys = [k for k in state_dict if any(re.fullmatch(p.replace('.*', '.*'), k) for p in src)]
    assert len(keys) == 1, f'Chunk expects exactly 1 source key, matched: {keys}'
    tensor = state_dict[keys[0]]
    n = len(transform.target_patterns)
    assert n > 1, 'Chunk requires >1 target pattern'
    assert tensor.size(0) % n == 0 or tensor.size(0) >= n, (
        f'tensor dim {tensor.shape} cannot be chunked into {n} parts'
    )

def is_valid_chunk_config(source_keys: list[str], tensor: "torch.Tensor", n_targets: int) -> bool:
    return len(source_keys) == 1 and n_targets > 1 and tensor.size(0) >= n_targets and tensor.size(0) % n_targets == 0

When it happens

Trigger: Registering a Chunk(dim=...) op in a WeightConverter where: (a) source_patterns matches multiple checkpoint keys, (b) target_patterns has length 1, or (c) the fused checkpoint tensor's size along `dim` is smaller than / not evenly splittable into len(target_patterns) chunks (e.g. splitting a 2-tensor fused QKV into 3 targets, or N targets where N does not divide the dimension).

Common situations: Writing a custom conversion recipe for a new checkpoint variant (e.g. fused QKV or fused gate/up projections being split into HF-style separate weights), or when the upstream checkpoint changes how it fuses layers between releases so the split arity no longer matches.

Related errors

• Conv3dToLinear expects a 5D or 2D tensor, got {tensor.ndim}D
• PermuteForRope expects a single tensor per key.
• Expected pattern {key} in collected tensors but only found t
• Unknown error
• Cannot reshape tensor with shape {tensor.shape} into {target

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