huggingface/transformers · error · ValueError

The following `model_kwargs` are not used by the model: {unu

Error message

The following `model_kwargs` are not used by the model: {unused_model_args} (note: typos in the generate arguments will also show up in this list)

What it means

After `generate` strips arguments it handles itself, every remaining kwarg must be consumed by the model's `prepare_inputs_for_generation` signature or be a known model-agnostic `TransformersKwargs` key (with a non-None value). Anything left over is reported as unused — this is the main typo/misspelling detector for generate arguments.

Source

Thrown at src/transformers/generation/utils.py:1664

            if decoder is None and base_model is not None:
                decoder = getattr(base_model, "decoder", None)

            if decoder is not None:
                decoder_model_args = set(inspect.signature(decoder.forward).parameters)
                model_args |= {f"decoder_{x}" for x in decoder_model_args}

        # TransformersKwargs are model-agnostic attention and generation arguments such as 'output_attentions'
        for key, value in model_kwargs.items():
            if (
                value is not None
                and key not in model_args
                and key not in TransformersKwargs.__optional_keys__
                and key != "debug_io"
            ):
                unused_model_args.append(key)

        if unused_model_args:
            raise ValueError(
                f"The following `model_kwargs` are not used by the model: {unused_model_args} (note: typos in the"
                " generate arguments will also show up in this list)"
            )

    def _validate_generated_length(
        self: "GenerativePreTrainedModel", generation_config, input_ids_length, has_default_max_length
    ):
        """Performs validation related to the resulting generated length"""
        # 1. Max length warnings related to poor parameterization
        if has_default_max_length and generation_config.max_new_tokens is None:
            # 20 is the default max_length of the generation config
            warnings.warn(
                f"Using the model-agnostic default `max_length` (={generation_config.max_length}) to control the "
                "generation length. We recommend setting `max_new_tokens` to control the maximum length of the "
                "generation.",
                UserWarning,
            )
        if input_ids_length >= generation_config.max_length:

View on GitHub (pinned to a597f97485)

Solutions

1. Read the listed names and fix typos against the `generate` documentation (e.g. `max_new_token` -> `max_new_tokens`).
2. If the kwarg is model-specific, confirm this model's `prepare_inputs_for_generation` accepts it; otherwise remove it.
3. Split kwargs: keep generation options in the generate call and tokenizer outputs in `model_inputs`; don't splat one dict into both.
4. For custom models, add the parameter to `prepare_inputs_for_generation` (and to its forward path) or unset it (None values are ignored).

Example fix

# before
out = model.generate(**inputs, max_new_token=64, temprature=0.7)
# ValueError: `model_kwargs` not used: ['max_new_token', 'temprature']

# after
out = model.generate(**inputs, max_new_tokens=64, temperature=0.7)

import inspect
valid = set(inspect.signature(model.prepare_inputs_for_generation).parameters) | {
    "max_new_tokens", "min_new_tokens", "do_sample", "temperature", "top_k", "top_p",
    "num_beams", "num_return_sequences", "repetition_penalty", "eos_token_id",
    "pad_token_id", "max_length", "stopping_criteria", "output_scores", "return_dict_in_generate",
}
typos = [k for k in user_kwargs if k not in valid]
if typos:
    raise ValueError(f"Possible typos in generate kwargs: {typos}")

try:
    out = model.generate(**inputs, **gen_kwargs)
except ValueError as e:
    if "not used by the model" in str(e):
        import re
        unused = re.search(r"\[([^\]]+)\]", str(e))
        for k in [u.strip().strip("'") for u in unused.group(1).split(",")]:
            gen_kwargs.pop(k, None)
        out = model.generate(**inputs, **gen_kwargs)
    else:
        raise

When it happens

Trigger: `model.generate(**inputs, max_new_token=50)` (missing 's'), `temprature=0.7`, passing a model-specific argument (e.g. `pixel_values`-adjacent keys or `attention_mask=attention` typos) to a model whose `prepare_inputs_for_generation` does not accept it, or passing `'output_scores'`-style keys not in the allowed set.

Common situations: Typos in long generate call lists; passing decoder-only arguments to encoder-decoder models (or vice versa) whose signatures differ; kwargs meant for the tokenizer accidentally forwarded to generate; custom models with narrow `prepare_inputs_for_generation` signatures.

Related errors

• `temperature` (={temperature}) has to be a strictly positive
• `penalty` has to be a strictly positive float, but is {penal
• `prompt_ignore_length` has to be a positive integer, but is
• `top_p` has to be a float > 0 and < 1, but is {top_p}
• `min_tokens_to_keep` has to be a positive integer, but is {m

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