huggingface/transformers · error · ValueError

Unsupported backward dtype: {config.backward_dtype}

Error message

Unsupported backward dtype: {config.backward_dtype}

What it means

Companion guard to the forward-dtype check in adapt_fp_quant_config: the backward (master-weight/gradient) dtype must be one of "bf16", "mxfp8", or "mxfp4" to map onto FPQuantDtype.BF16/MXFP8/MXFP4. Any other string (typos, unsupported formats like "fp16" or "nvfp4") raises ValueError with the offending value.

Source

Thrown at src/transformers/integrations/fp_quant.py:134

            }


def adapt_fp_quant_config(config: FPQuantConfig):
    if config.forward_dtype == "mxfp4":
        forward_dtype = FPQuantDtype.MXFP4
    elif config.forward_dtype == "nvfp4":
        forward_dtype = FPQuantDtype.NVFP4
    else:
        raise ValueError(f"Unsupported forward dtype: {config.forward_dtype}")

    if config.backward_dtype == "bf16":
        backward_dtype = FPQuantDtype.BF16
    elif config.backward_dtype == "mxfp8":
        backward_dtype = FPQuantDtype.MXFP8
    elif config.backward_dtype == "mxfp4":
        backward_dtype = FPQuantDtype.MXFP4
    else:
        raise ValueError(f"Unsupported backward dtype: {config.backward_dtype}")

    return FPQuantLinearConfig(
        forward_dtype=forward_dtype,
        forward_method=config.forward_method,
        backward_dtype=backward_dtype,
        store_master_weights=config.store_master_weights,
        hadamard_group_size=config.hadamard_group_size,
        pseudoquantization=config.pseudoquantization,
        transform_init=config.transform_init,
        modules_to_not_convert=config.modules_to_not_convert,
    )

View on GitHub (pinned to a597f97485)

Solutions

1. Use one of "bf16", "mxfp8", or "mxfp4" (exact lowercase) for backward_dtype
2. Inspect and fix the quantization_config block in the checkpoint's config.json
3. Upgrade transformers if the checkpoint uses a newly added backward dtype

Example fix

# before
quant = FPQuantConfig(forward_dtype="nvfp4", backward_dtype="fp16")

# after
quant = FPQuantConfig(forward_dtype="nvfp4", backward_dtype="bf16")

VALID_BACKWARD = {"bf16", "mxfp8", "mxfp4"}
assert qc.backward_dtype in VALID_BACKWARD, f"backward_dtype must be one of {VALID_BACKWARD}, got {qc.backward_dtype!r}"

def is_valid_backward_dtype(v: str) -> bool:
    return isinstance(v, str) and v in {"bf16", "mxfp8", "mxfp4"}

When it happens

Trigger: Creating FPQuantConfig(backward_dtype=...) with an unmapped string, or loading a checkpoint whose quantization_config JSON stores a backward_dtype this transformers version does not recognize.

Common situations: Assuming fp16 is allowed for backward compute; copying a config between ecosystems; older checkpoints written before the supported set changed; case-sensitive typos ("BF16").

Related errors

• Unsupported forward dtype: {config.forward_dtype}
• `nbits` for `quanto` backend has to be one of [`2`, `4`] but
• `axis_key` for `quanto` backend has to be one of [`0`, `-1`]
• `axis_value` for `quanto` backend has to be one of [`0`, `-1
• `nbits` for `HQQ` backend has to be one of [`1`, `2`, `3`, `

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