hiyouga/LlamaFactory · error · ValueError

Some specified arguments are not used by the HfArgumentParse

Error message

Some specified arguments are not used by the HfArgumentParser: {unknown_args}

What it means

Raised by _parse_args when HfArgumentParser.parse_args_into_dataclasses returns leftover strings, i.e. CLI tokens that match no field in any of the argument dataclasses (and allow_extra_keys is false). The parser prints full help plus the offending list before raising, so the unknown tokens are shown in the log right above the traceback.

Source

Thrown at src/llamafactory/hparams/parser.py:161

        local_batch_sizes.append(training_args.per_device_train_batch_size)
    if training_args.do_eval or training_args.do_predict:
        local_batch_sizes.append(training_args.per_device_eval_batch_size)
    return tokens_per_sample * max(local_batch_sizes)


def _parse_args(
    parser: "HfArgumentParser", args: dict[str, Any] | list[str] | None = None, allow_extra_keys: bool = False
) -> tuple[Any]:
    args = read_args(args)
    if isinstance(args, dict):
        return parser.parse_dict(args, allow_extra_keys=allow_extra_keys)

    (*parsed_args, unknown_args) = parser.parse_args_into_dataclasses(args=args, return_remaining_strings=True)

    if unknown_args and not allow_extra_keys:
        print(parser.format_help())
        print(f"Got unknown args, potentially deprecated arguments: {unknown_args}")
        raise ValueError(f"Some specified arguments are not used by the HfArgumentParser: {unknown_args}")

    return tuple(parsed_args)


def _verify_trackio_args(training_args: "TrainingArguments") -> None:
    """Validates Trackio-specific arguments.

    Args:
        training_args: TrainingArguments instance (not a dictionary)
    """
    report_to = training_args.report_to
    if not report_to:
        return

    if isinstance(report_to, str):
        report_to = [report_to]

    if "trackio" not in report_to:

View on GitHub (pinned to f28afaf635)

Solutions

1. Read the `Got unknown args` line above the error and correct each flag name against the printed help.
2. If the flag was renamed in a newer release, update the script to the current name (check CHANGELOG / parser.py dataclasses).
3. Programmatic callers that genuinely need extra keys can pass allow_extra_keys=True where the API permits.

Example fix

# before (bash)
llamafactory-cli train cfg.yaml --cut_off_len 4096

# after (bash)
llamafactory-cli train cfg.yaml --cutoff_len 4096

import inspect
from llamafactory.hparams.parser import _TRAIN_CLS  # dataclass tuple
valid = set()
for cls in _TRAIN_CLS:
    valid.update(f.name for f in dataclasses.fields(cls))
bad = [a for a in cli_tokens if a.startswith('--') and a[2:].split(' ')[0].replace('-', '_') not in valid]
assert not bad, f'unknown flags: {bad}'

def is_known_flag(flag: str, valid_fields: set[str]) -> bool:
    return flag.lstrip('-').replace('-', '_') in valid_fields

When it happens

Trigger: Invoking llamafactory-cli (or calling _parse_args with a CLI-style list) with mistyped or removed flags, e.g. `--cut_off_len 4096` instead of `--cutoff_len`, or args renamed/removed in a newer LLaMA-Factory version.

Common situations: Upgrading LlamaFactory and re-running old shell scripts; flags like `--per_device_trainf_batch_size` typos; passing webui-era or v1-only flags to the v0 CLI.

Related errors

• Template {data_args.template} does not exist.
• Tool utils `{name}` not found.
• KTransformers uses LLaMA-Factory's `disable_gradient_checkpo
• KTransformers supplies its checkpoint context; remove `gradi
• Disable FSDP activation checkpointing when using KTransforme

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/faec5440ab0a109b. Report an issue: GitHub.