microsoft/qlib · error · ValueError

report_factor should be one of annualized_return…

Error message

report_factor should be one of annualized_return, information_ratio, max_drawdown, mean, std, model_pearsonr and model_score

What it means

OptimizationConfig (qlib/contrib/tuner/config.py) validates the report_factor field: only annualized_return, information_ratio, max_drawdown, mean, std, model_score, and model_pearsonr are allowed. This factor is the metric the tuner optimizes over the chosen report, so an unknown metric cannot be ranked and the config is rejected immediately.

Solutions

1. Use one of the supported factors: annualized_return, information_ratio, max_drawdown, mean, std, model_score, model_pearsonr
2. Check exact lowercase spelling in optimization_criteria.report_factor
3. If you truly need a custom metric, subclass OptimizationConfig or post-process the tuner's report instead of adding the value to YAML

Example fix

# before (tuner_config.yaml)
optimization_criteria:
  report_factor: sharpe_ratio

# after
optimization_criteria:
  report_factor: information_ratio

VALID_FACTORS = {'annualized_return', 'information_ratio', 'max_drawdown', 'mean', 'std', 'model_score', 'model_pearsonr'}
assert cfg['optimization_criteria']['report_factor'] in VALID_FACTORS

def is_valid_report_factor(f: str) -> bool:
    return f in {'annualized_return', 'information_ratio', 'max_drawdown', 'mean', 'std', 'model_score', 'model_pearsonr'}

When it happens

Trigger: A tuner YAML with optimization_criteria: report_factor: sharpe (or any value outside the whitelist, including case variants like 'Information_Ratio') raises ValueError when TunerConfigManager loads it.

Common situations: Wanting a custom metric (Sharpe ratio, win rate) that the tuner never supported; typo or case mismatch; configs written for a different qlib version with a different whitelist.

Related errors

• Config path is invalid.
• optim_type should be min, max or correlation
• report_type should be one of pred_long, pred_long_short…
• Please give the search space of model.
• Please give the search space of strategy.

AI-assisted analysis of microsoft/qlib@79633dd950 (2026-08-15). Data as JSON: /api/errors/4c0c7d9cb95de89b. Report an issue: GitHub.

Appendix: source

Thrown at qlib/contrib/tuner/config.py:84

            "excess_return_without_cost",
            "excess_return_with_cost",
            "model",
        ]:
            raise ValueError(
                "report_type should be one of pred_long, pred_long_short, pred_short, excess_return_without_cost, excess_return_with_cost and model"
            )

        self.report_factor = config.get("report_factor", "information_ratio")
        if self.report_factor not in [
            "annualized_return",
            "information_ratio",
            "max_drawdown",
            "mean",
            "std",
            "model_score",
            "model_pearsonr",
        ]:
            raise ValueError(
                "report_factor should be one of annualized_return, information_ratio, max_drawdown, mean, std, model_pearsonr and model_score"
            )

        self.optim_type = config.get("optim_type", "max")
        if self.optim_type not in ["min", "max", "correlation"]:
            raise ValueError("optim_type should be min, max or correlation")

View on GitHub (pinned to 79633dd950)