{"record":{"id":"18445293caca753c","repo":"hiyouga/LlamaFactory","slug":"some-specified-arguments-are-not-used-by-the-hfarg-184452","errorCode":null,"errorMessage":"Some specified arguments are not used by the HfArgumentParser: {unknown_args}","messagePattern":"Some specified arguments are not used by the HfArgumentParser: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/v1/config/arg_parser.py","lineNumber":58,"sourceCode":"        if len(sys.argv) > 1 and (sys.argv[1].endswith(\".yaml\") or sys.argv[1].endswith(\".yml\")):\n            override_config = OmegaConf.from_cli(sys.argv[2:])\n            dict_config = OmegaConf.load(Path(sys.argv[1]).absolute())\n            args = OmegaConf.to_container(OmegaConf.merge(dict_config, override_config))\n        elif len(sys.argv) > 1 and sys.argv[1].endswith(\".json\"):\n            override_config = OmegaConf.from_cli(sys.argv[2:])\n            dict_config = OmegaConf.create(json.load(Path(sys.argv[1]).absolute()))\n            args = OmegaConf.to_container(OmegaConf.merge(dict_config, override_config))\n        else:  # list of strings\n            args = sys.argv[1:]\n\n    if isinstance(args, dict):\n        (*parsed_args,) = parser.parse_dict(args, allow_extra_keys=allow_extra_keys)\n    else:\n        (*parsed_args, unknown_args) = parser.parse_args_into_dataclasses(args, return_remaining_strings=True)\n        if unknown_args and not allow_extra_keys:\n            print(parser.format_help())\n            print(f\"Got unknown args, potentially deprecated arguments: {unknown_args}\")\n            raise ValueError(f\"Some specified arguments are not used by the HfArgumentParser: {unknown_args}\")\n\n    model_args, data_args, training_args, sample_args = parsed_args\n    # Seed as early as possible after argument parsing so all downstream\n    # components (dist init, dataloader, model init in run_* entrypoints) share the same RNG state.\n    set_seed(training_args.seed, full_determinism=training_args.full_determinism)\n\n    return model_args, data_args, training_args, sample_args\n\n\nif __name__ == \"__main__\":\n    print(get_args())\n","sourceCodeStart":40,"sourceCodeEnd":70,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/v1/config/arg_parser.py#L40-L70","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nllamafactory-cli train config.yaml  # yaml contains v0-only key `template: llama3`\n\n# after\n# remove/translate v0 keys; v1 uses renderer/model args instead of `template`","handlingStrategy":"validation","validationCode":"from dataclasses import fields\nfrom llamafactory.v1.config.model_args import ModelArguments\n# repeat for the other three dataclasses\n\nVALID_KEYS = {f.name for cls in (ModelArguments,) for f in fields(cls)}\n\ndef lint_config(config: dict) -> list[str]:\n    return [k for k in config if k not in VALID_KEYS]  # warn before running","typeGuard":null,"tryCatchPattern":"try:\n    get_args()\nexcept ValueError as e:\n    if \"not used by the HfArgumentParser\" in str(e):\n        # parser already printed help + unknown list; surface to config author\n        raise SystemExit(\"Fix or remove the listed keys in the v1 config\") from e\n    raise","preventionTips":["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"],"tags":["v1","configuration","cli","argument-parsing"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}