What causes "unknown base model name `%s`" in microsoft/qlib?

Set base_model to exactly 'GRU' or 'LSTM' (case-sensitive) when constructing HISTModel

microsoft/qlib · error · ValueError

unknown base model name `%s`

Error message

unknown base model name `%s`

What it means

HISTModel.fit only knows how to build a pretrained base model for two names: 'LSTM' (LSTMModel) and 'GRU' (GRUModel). Any other value of self.base_model raises this ValueError before training starts, because the pretrained-weight transfer into the HIST graph requires one of those two architectures.

Source

Thrown at qlib/contrib/model/pytorch_hist.py:285

        x_train, y_train, stock_index_train = df_train["feature"], df_train["label"], df_train["stock_index"]
        x_valid, y_valid, stock_index_valid = df_valid["feature"], df_valid["label"], df_valid["stock_index"]

        save_path = get_or_create_path(save_path)

        stop_steps = 0
        best_score = -np.inf
        best_epoch = 0
        evals_result["train"] = []
        evals_result["valid"] = []

        # load pretrained base_model
        if self.base_model == "LSTM":
            pretrained_model = LSTMModel()
        elif self.base_model == "GRU":
            pretrained_model = GRUModel()
        else:
            raise ValueError("unknown base model name `%s`" % self.base_model)

        if self.model_path is not None:
            self.logger.info("Loading pretrained model...")
            pretrained_model.load_state_dict(torch.load(self.model_path))

        model_dict = self.HIST_model.state_dict()
        pretrained_dict = {
            k: v for k, v in pretrained_model.state_dict().items() if k in model_dict  # pylint: disable=E1135
        }
        model_dict.update(pretrained_dict)
        self.HIST_model.load_state_dict(model_dict)
        self.logger.info("Loading pretrained model Done...")

        # train
        self.logger.info("training...")
        self.fitted = True

        for step in range(self.n_epochs):

View on GitHub (pinned to 79633dd950)

Solutions

Set base_model to exactly 'GRU' or 'LSTM' (case-sensitive) when constructing HISTModel
If you configured via workflow YAML, check task -> model -> kwargs -> base_model
If you need a different base architecture, subclass HISTModel and extend the if/elif chain in fit with your model class

Example fix

# before
model = HISTModel(base_model="Transformer")

# after
model = HISTModel(base_model="GRU")

Defensive patterns

Strategy: validation

Validate before calling

assert model.base_model in ("LSTM", "GRU"), f"base_model must be LSTM or GRU, got {model.base_model!r}"

Type guard

def is_valid_hist_base_model(name: str) -> bool:
    return name in ("LSTM", "GRU")

Try / catch

try:
    model.fit(dataset)
except ValueError as e:
    if "unknown base model" in str(e):
        model.base_model = "GRU"  # or fail config validation earlier
    else:
        raise

Prevention

Validate base_model against the model's supported set when parsing config
Keep per-model config files rather than one shared hyperparameter block

When it happens

Trigger: Constructing HISTModel(d_model=..., base_model='Transformer') or any string other than 'LSTM'/'GRU' (including lowercase 'lstm', 'gru', or None) and then calling fit().

Common situations: Copying a config from another qlib model (e.g. pytorch_transformer or ADD) whose model_type is Transformer/ALSTM and passing it to HIST unchanged; case mismatch ('gru' vs 'GRU'); typo in the workflow YAML task.model.class argument.

Related errors

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