hiyouga/LlamaFactory · error · ValueError

`--project` must be specified when using Trackio.

Error message

`--project` must be specified when using Trackio.

What it means

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.

Source

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

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:
        return

    # --- Enforce project (required by Trackio) ---
    if not training_args.project:
        raise ValueError("`--project` must be specified when using Trackio.")

    # --- Validate trackio_space_id format ---
    space_id = training_args.trackio_space_id
    if space_id:
        if space_id != "trackio" and "/" not in space_id:
            logger.warning(
                f"trackio_space_id '{space_id}' should typically be in format "
                "'org/space' for Hugging Face Spaces deployment."
            )

    # --- Inform about default project usage ---
    if training_args.project == "huggingface":
        logger.info(
            "Using default project name 'huggingface'. "
            "Consider setting a custom project name with --project "
            "for better organization."
        )

View on GitHub (pinned to f28afaf635)

Solutions

1. Add `project: <your-project-name>` to the training YAML / `--project name` on the CLI.
2. Prefer a specific name over the default 'huggingface' to keep Spaces organized (the code only logs info for that default).

Example fix

# before (yaml)
report_to: trackio

# after (yaml)
report_to: trackio
project: lora-sft-experiments

if 'trackio' in (cfg.get('report_to') or []) and not cfg.get('project'):
    raise SystemExit('set project: <name> when reporting to trackio')

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• KTransformers uses LLaMA-Factory's `disable_gradient_checkpo
• KTransformers supplies its checkpoint context; remove `gradi
• Disable FSDP activation checkpointing when using KTransforme
• KTransformers thin integration currently supports LoRA finet
• `kt_model_max_length` must be a positive integer.

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