{"record":{"id":"9f27066b2448d3ef","repo":"hiyouga/LlamaFactory","slug":"project-must-be-specified-when-using-trackio","errorCode":null,"errorMessage":"`--project` must be specified when using Trackio.","messagePattern":"`--project` must be specified when using Trackio\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/parser.py","lineNumber":184,"sourceCode":"def _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:\n        return\n\n    # --- Enforce project (required by Trackio) ---\n    if not training_args.project:\n        raise ValueError(\"`--project` must be specified when using Trackio.\")\n\n    # --- Validate trackio_space_id format ---\n    space_id = training_args.trackio_space_id\n    if space_id:\n        if space_id != \"trackio\" and \"/\" not in space_id:\n            logger.warning(\n                f\"trackio_space_id '{space_id}' should typically be in format \"\n                \"'org/space' for Hugging Face Spaces deployment.\"\n            )\n\n    # --- Inform about default project usage ---\n    if training_args.project == \"huggingface\":\n        logger.info(\n            \"Using default project name 'huggingface'. \"\n            \"Consider setting a custom project name with --project \"\n            \"for better organization.\"\n        )\n","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/parser.py#L166-L202","documentation":"Raised by _verify_trackio_args when report_to includes 'trackio' but training_args.project is empty. Trackio uploads runs to a Hugging Face Space that is keyed by project name, so the project is a hard prerequisite rather than an optional label.","triggerScenarios":"A training YAML or CLI with `report_to: trackio` but no `project:` key; _verify_trackio_args returns early only when report_to is empty or lacks trackio, otherwise the missing project aborts.","commonSituations":"Users add trackio to report_to copying from tensorboard-style configs where no project name is needed, or they set `--hub_project`/run_name believing one of them covers it.","solutions":["Add `project: <your-project-name>` to the training YAML / `--project name` on the CLI.","Prefer a specific name over the default 'huggingface' to keep Spaces organized (the code only logs info for that default)."],"exampleFix":"# before (yaml)\nreport_to: trackio\n\n# after (yaml)\nreport_to: trackio\nproject: lora-sft-experiments","handlingStrategy":"validation","validationCode":"if 'trackio' in (cfg.get('report_to') or []) and not cfg.get('project'):\n    raise SystemExit('set project: <name> when reporting to trackio')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat project as required metadata whenever trackio is in report_to.","Add a config lint for reporter-specific required keys."],"tags":["trackio","reporting","config","llamafactory"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}