HKUDS/Vibe-Trading · error · ValueError

run_card_path or backtest_run_dir is required

Error message

run_card_path or backtest_run_dir is required

What it means

HypothesisRegistry.link_backtest requires at least one of run_card_path or backtest_run_dir to identify the backtest being attached to a hypothesis. Both defaulting to empty/None means there is nothing to link, so the call is rejected before mutation.

Source

Thrown at agent/src/hypotheses/registry.py:312

        Args:
            hypothesis_id: Registry identifier.
            run_card_path: Optional path to a run_card.json.
            backtest_run_dir: Optional backtest run directory.
            metrics: Optional metrics summary.
            validation: Optional walk-forward/Monte-Carlo/bootstrap robustness
                results, as written by write_run_card's top-level
                "validation" key (a sibling of "metrics", not nested in it).
            notes: Optional human note about the link.

        Returns:
            Updated hypothesis.

        Raises:
            KeyError: If the hypothesis does not exist.
            ValueError: If no run card or run directory is provided.
        """
        if not run_card_path and not backtest_run_dir:
            raise ValueError("run_card_path or backtest_run_dir is required")
        records = self.list()
        hyp = self._find_required(records, hypothesis_id)
        run_card_record: dict[str, Any] = {
            "run_card_path": run_card_path,
            "backtest_run_dir": backtest_run_dir,
            "metrics": metrics or {},
            "notes": notes,
            "linked_at": _utc_now(),
        }
        if validation is not None:
            run_card_record["validation"] = validation
        hyp.run_cards.append(run_card_record)
        hyp.updated_at = _utc_now()
        self._save(records)
        return hyp

    def search(
        self,

View on GitHub (pinned to 80ffdda44c)

Solutions

  1. Pass the run card file path produced by the backtest executor
  2. Or pass the backtest run directory if no single run card exists
  3. Guard the call: only link after confirming the backtest produced a path/dir

Example fix

# before
registry.link_backtest(hid)
# after
registry.link_backtest(hid, run_card_path=run.run_card_path)
Defensive patterns

Strategy: validation

Validate before calling

if not (run_card_path or backtest_run_dir):
    raise ValueError('nothing to link: backtest produced no artifacts')
registry.link_backtest(hid, run_card_path=run_card_path, backtest_run_dir=backtest_run_dir)

Type guard

def has_link_target(rc, rd) -> bool:
    return bool(str(rc or '').strip() or str(rd or '').strip())

Try / catch

try:
    registry.link_backtest(hid, run_card_path=rc)
except ValueError as exc:
    if 'required' in str(exc):
        log.warning('skipping link for %s: no run artifacts', hid)

Prevention

When it happens

Trigger: Calling link_backtest(hid, run_card_path=None, backtest_run_dir=None), or passing '' for both because the backtest job failed to produce a run card path.

Common situations: Linking a hypothesis to a backtest run whose artifacts weren't generated (job crashed), or wiring up the call before the path variables are populated.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/01f2b2ffdbeb32c3. Report an issue: GitHub.