{"record":{"id":"faec5440ab0a109b","repo":"hiyouga/LlamaFactory","slug":"some-specified-arguments-are-not-used-by-the-hfarg","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":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/parser.py","lineNumber":161,"sourceCode":"        local_batch_sizes.append(training_args.per_device_train_batch_size)\n    if training_args.do_eval or training_args.do_predict:\n        local_batch_sizes.append(training_args.per_device_eval_batch_size)\n    return tokens_per_sample * max(local_batch_sizes)\n\n\ndef _parse_args(\n    parser: \"HfArgumentParser\", args: dict[str, Any] | list[str] | None = None, allow_extra_keys: bool = False\n) -> tuple[Any]:\n    args = read_args(args)\n    if isinstance(args, dict):\n        return parser.parse_dict(args, allow_extra_keys=allow_extra_keys)\n\n    (*parsed_args, unknown_args) = parser.parse_args_into_dataclasses(args=args, return_remaining_strings=True)\n\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    return tuple(parsed_args)\n\n\ndef _verify_trackio_args(training_args: \"TrainingArguments\") -> None:\n    \"\"\"Validates Trackio-specific arguments.\n\n    Args:\n        training_args: TrainingArguments instance (not a dictionary)\n    \"\"\"\n    report_to = training_args.report_to\n    if not report_to:\n        return\n\n    if isinstance(report_to, str):\n        report_to = [report_to]\n\n    if \"trackio\" not in report_to:","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/parser.py#L143-L179","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the `Got unknown args` line above the error and correct each flag name against the printed help.","If the flag was renamed in a newer release, update the script to the current name (check CHANGELOG / parser.py dataclasses).","Programmatic callers that genuinely need extra keys can pass allow_extra_keys=True where the API permits."],"exampleFix":"# before (bash)\nllamafactory-cli train cfg.yaml --cut_off_len 4096\n\n# after (bash)\nllamafactory-cli train cfg.yaml --cutoff_len 4096","handlingStrategy":"validation","validationCode":"import inspect\nfrom llamafactory.hparams.parser import _TRAIN_CLS  # dataclass tuple\nvalid = set()\nfor cls in _TRAIN_CLS:\n    valid.update(f.name for f in dataclasses.fields(cls))\nbad = [a for a in cli_tokens if a.startswith('--') and a[2:].split(' ')[0].replace('-', '_') not in valid]\nassert not bad, f'unknown flags: {bad}'","typeGuard":"def is_known_flag(flag: str, valid_fields: set[str]) -> bool:\n    return flag.lstrip('-').replace('-', '_') in valid_fields","tryCatchPattern":null,"preventionTips":["Prefer YAML configs over long CLI flag lists.","Re-validate driver scripts after major version bumps.","Use shell completion / --help to confirm flag names."],"tags":["cli","arguments","typo","llamafactory"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}