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

The v1 argument parser (`src/llamafactory/v1/config/arg_parser.py`) parses argv into the four v1 dataclasses with `return_remaining_strings=True`; any unrecognized flag raises this ValueError unless `allow_extra_keys` is set. It exists to catch v0-only or misspelled arguments early instead of silently ignoring them. The parser prints full help plus the offending list right before raising.

Source

Thrown at src/llamafactory/v1/config/arg_parser.py:58

        if len(sys.argv) > 1 and (sys.argv[1].endswith(".yaml") or sys.argv[1].endswith(".yml")):
            override_config = OmegaConf.from_cli(sys.argv[2:])
            dict_config = OmegaConf.load(Path(sys.argv[1]).absolute())
            args = OmegaConf.to_container(OmegaConf.merge(dict_config, override_config))
        elif len(sys.argv) > 1 and sys.argv[1].endswith(".json"):
            override_config = OmegaConf.from_cli(sys.argv[2:])
            dict_config = OmegaConf.create(json.load(Path(sys.argv[1]).absolute()))
            args = OmegaConf.to_container(OmegaConf.merge(dict_config, override_config))
        else:  # list of strings
            args = sys.argv[1:]

    if isinstance(args, dict):
        (*parsed_args,) = parser.parse_dict(args, allow_extra_keys=allow_extra_keys)
    else:
        (*parsed_args, unknown_args) = parser.parse_args_into_dataclasses(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}")

    model_args, data_args, training_args, sample_args = parsed_args
    # Seed as early as possible after argument parsing so all downstream
    # components (dist init, dataloader, model init in run_* entrypoints) share the same RNG state.
    set_seed(training_args.seed, full_determinism=training_args.full_determinism)

    return model_args, data_args, training_args, sample_args


if __name__ == "__main__":
    print(get_args())

View on GitHub (pinned to f28afaf635)

Solutions

Read the printed `unknown_args` list and remove/rename each key to its v1 equivalent (consult v1 dataclasses in `src/llamafactory/v1/config/`)
Check the printed parser help for the exact accepted field names
For programmatic callers that validated keys already, pass `allow_extra_keys=True` to `get_args()` to tolerate extras

Example fix

# before
llamafactory-cli train config.yaml  # yaml contains v0-only key `template: llama3`

# after
# remove/translate v0 keys; v1 uses renderer/model args instead of `template`

Defensive patterns

Strategy: validation

Validate before calling

from dataclasses import fields
from llamafactory.v1.config.model_args import ModelArguments
# repeat for the other three dataclasses

VALID_KEYS = {f.name for cls in (ModelArguments,) for f in fields(cls)}

def lint_config(config: dict) -> list[str]:
    return [k for k in config if k not in VALID_KEYS]  # warn before running

Try / catch

try:
    get_args()
except ValueError as e:
    if "not used by the HfArgumentParser" in str(e):
        # parser already printed help + unknown list; surface to config author
        raise SystemExit("Fix or remove the listed keys in the v1 config") from e
    raise

Prevention

Keep separate config files for v0 and v1
Run a config lint step in CI that diffs keys against the v1 dataclasses
Read the parser's printed help when porting instead of guessing key names

When it happens

Trigger: Running a v1 train command with flags from the v0 grammar (e.g. `lora_target`, `template`, `packing`) or with typos, when those fields do not exist on the v1 `ModelArguments`/`DataArguments`/`TrainingArguments`/`SampleArguments` dataclasses.

Common situations: Porting an existing v0 YAML/CLI to `USE_V1=1` without translating field names; IDE autocompleting a stale key; a shared config template used by both architectures.

Related errors

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