huggingface/pytorch-image-models · error · ValueError

Unknown coefficients preset '{value}'. Valid options: {valid

Error message

Unknown coefficients preset '{value}'. Valid options: {valid}

What it means

Muon ships named presets of Newton–Schulz coefficient schedules; requesting a preset name that is not in the registry raises this error, listing the valid options.

Source

Thrown at timm/optim/muon.py:1032

def resolve_ns_coefficients(
        value: Union[str, Sequence[float], Sequence[Sequence[float]]],
        presets: Mapping[str, Sequence[Sequence[float]]]
) -> List[Tuple[float, float, float]]:
    # tiny helpers (kept inline for succinctness)
    is_seq = lambda x: isinstance(x, Sequence) and not isinstance(x, (str, bytes))
    is_real = lambda x: isinstance(x, numbers.Real) and not isinstance(x, bool)

    def as_coeff(x: Sequence[float]) -> Tuple[float, float, float]:
        if not is_seq(x) or len(x) != 3 or not all(is_real(v) for v in x):
            raise ValueError(f"Coefficient must be length-3 of real numbers, got: {x!r}")
        a, b, c = x  # type: ignore[misc]
        return float(a), float(b), float(c)

    if isinstance(value, str):
        if value not in presets:
            valid = ", ".join(sorted(presets.keys()))
            raise ValueError(f"Unknown coefficients preset '{value}'. Valid options: {valid}")
        seq = presets[value]
        if not is_seq(seq) or len(seq) == 0:
            raise ValueError(f"Preset '{value}' is empty or invalid")
        return [as_coeff(item) for item in seq]  # validate & cast

    if not is_seq(value):
        raise TypeError(
            "Coefficients must be a preset name (str), a 3-sequence (a,b,c), "
            "or a sequence of 3-sequences."
        )

    # Decide single triple vs list-of-triples by structure
    if len(value) == 3 and all(is_real(v) for v in value):  # type: ignore[index]
        return [as_coeff(value)]  # single triple -> wrap

    # Otherwise treat as list/tuple of triples
    out = []
    for i, item in enumerate(value):  # type: ignore[assignment]

View on GitHub (pinned to 9a5261e31b)

Solutions

  1. Use one of the preset names listed in the error message (the valid sorted keys)
  2. Pass an explicit list of coefficient triples instead of a preset name
  3. Check the installed timm version's muon.py for the current preset registry

Example fix

# before
Muon(params, ns_coefficients="fast")
# after
Muon(params, ns_coefficients="modular")  # use a name from the error's valid list
Defensive patterns

Strategy: validation

Validate before calling

from timm.optim.muon import resolve_ns_coefficients
try:
    resolve_ns_coefficients(cfg.ns_coefficients)
except ValueError as e:
    raise SystemExit(f'bad ns_coefficients: {e}')

Type guard

def is_valid_preset(name: str, presets: dict) -> bool:
    return name in presets

Try / catch

try:
    opt = Muon(params, ns_coefficients=cfg.preset)
except ValueError as e:
    if 'preset' in str(e):
        print(e)  # lists valid options; fall back to default
        opt = Muon(params)
    else:
        raise

Prevention

When it happens

Trigger: Calling Muon(params, ns_coefficients='shampoo') or resolve_ns_coefficients('typical') — any string not among the built-in preset keys.

Common situations: Guessing preset names; presets renamed/removed between timm versions; configs copied from other Muon implementations.

Related errors

AI-assisted analysis of huggingface/pytorch-image-models@9a5261e31b (2026-08-27). Data as JSON: /api/errors/aadf28dc6d853ef9. Report an issue: GitHub.