huggingface/transformers · error · ValueError

GroupWeightRename requires N:N length matching, but found le

Error message

GroupWeightRename requires N:N length matching, but found len(source_patterns)={len(source_patterns)} != len(target_patterns)={len(target_patterns)}

What it means

Raised by GroupWeightRename.__init__ (core_model_loading.py:1035). GroupWeightRename performs a coordinated set of renames guarded by a sentinel (guard) key, so it must have an exact 1:1 correspondence between source_patterns and target_patterns. If the two lists differ in length, the group semantics (which dependent rename maps to which guard) are undefined and construction fails immediately.

Source

Thrown at src/transformers/core_model_loading.py:1035

class GroupWeightRename(WeightRenaming):
    """
    Applies a list of paired WeightRenaming transforms, activated lazily by the first ("guard")
    source pattern.  Use this when two renames share an intermediate name (e.g. `norm0→norm1`
    and `norm1→norm2`) so that loading an already-converted checkpoint (which has `norm1`
    and `norm2` but no `norm0`) does not incorrectly re-apply the renames.

    NOTE: order `source_patterns` so that the one that is absent in an already-converted checkpoint
    comes first.  The state dict is iterated in sorted key order, so the guard pattern must be
    lexicographically smaller than the dependent patterns. Otherwise the dependents will be
    skipped on the first pass and never retried.
    """

    __slots__ = ("_active",)

    def __init__(self, source_patterns: list[str], target_patterns: list[str]):
        if len(source_patterns) != len(target_patterns):
            raise ValueError(
                "GroupWeightRename requires N:N length matching, but found "
                f"len(source_patterns)={len(source_patterns)} != len(target_patterns)={len(target_patterns)}"
            )
        super().__init__(source_patterns=source_patterns, target_patterns=target_patterns)
        self._active = None  # None = undecided; True = guard was seen

    def rename_source_key(self, source_key: str) -> tuple[str, str | None]:
        matched = self._scoped_match(source_key)
        if matched is None:
            return source_key, None

        prefix_dot, key_to_match, match_object = matched
        matching_group_name = next(name for name, val in match_object.groupdict().items() if val is not None)
        group_index = int(matching_group_name[1:])

        if group_index == 0:
            # Guard pattern matched — activate the group for subsequent keys
            self._active = True

View on GitHub (pinned to a597f97485)

Solutions

Count both lists and add the missing entry so len(source_patterns) == len(target_patterns).
Keep sources and targets as pairs in one list of tuples in your recipe source, then unzip — impossible to get out of sync.
Remember ordering matters too (see the class docstring: the guard pattern must sort lexicographically first).

Example fix

# before
GroupWeightRename(source_patterns=[r'norm0', r'norm1', r'norm2'], target_patterns=[r'ln_1', r'ln_2'])

# after
GroupWeightRename(source_patterns=[r'norm0', r'norm1', r'norm2'], target_patterns=[r'ln_1', r'ln_2', r'ln_3'])

Defensive patterns

Strategy: validation

Validate before calling

assert len(source_patterns) == len(target_patterns), (
    f'GroupWeightRename needs N:N, got {len(source_patterns)} sources vs {len(target_patterns)} targets'
)

Type guard

def is_paired_patterns(sources: list[str], targets: list[str]) -> bool:
    return len(sources) == len(targets)

Prevention

Store rename pairs as tuples in one list and unzip at construction so lengths can never diverge.
Order patterns so the guard key sorts first (per the class docstring).
Add an init-time unit test for each recipe's pattern lists.

When it happens

Trigger: GroupWeightRename(source_patterns=[a, b, c], target_patterns=[x, y]) — any length mismatch. Typically an editing mistake where one list was updated and the other was not.

Common situations: Maintaining conversion recipes that rename grouped checkpoints (e.g. norm0/norm1/norm2 style layouts where presence of one key implies the others). Adding a new pattern to source_patterns but forgetting the matching target, or vice versa.

Related errors

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