google-research/timesfm · error · ValueError

For XReg, `return_backcast` must be set to True in the forec

Error message

For XReg, `return_backcast` must be set to True in the forecast config. Please recompile the model.

What it means

When `xreg_mode` is 'timesfm + xreg' or 'xreg + timesfm', the library fits an OLS residual model on the backcast (the model's reconstruction of the training context), so the forecast config must have `return_backcast=True`. If compile() was called with return_backcast=False, covariate fitting is impossible and the library raises ValueError telling you to recompile. This is a config-inconsistency check, not a runtime failure.

Source

Thrown at src/timesfm/timesfm_2p5/timesfm_2p5_base.py:241

      static_categorical_covariates: A dict of static categorical covariates.
      xreg_mode: one of "xreg + timesfm" or "timesfm + xreg". "xreg + timesfm"
        first fits an XReg model on the targets, then uses TimesFM to forecast
        the residuals. "timesfm + xreg" first runs TimesFM to get a forecast,
        then fits an XReg model on the residuals of that forecast.
      normalize_xreg_target_per_input: whether to normalize the xreg target per
        input in the given batch.
      ridge: ridge penalty for the linear model.
      max_rows_per_col: max number of rows per column for the linear model.
      force_on_cpu: whether to force running on cpu for the linear model.

    Returns:
      A tuple of two lists. The first is the outputs of the model. The second is
      the outputs of the xreg.
    """
    if self.forecast_config is None:
      raise ValueError("Model is not compiled. Please call compile() first.")
    elif not self.forecast_config.return_backcast:
      raise ValueError(
        "For XReg, `return_backcast` must be set to True in the forecast config. Please recompile the model."
      )

    from ..utils import xreg_lib

    # Verify and bookkeep covariates.
    if not (
      dynamic_numerical_covariates
      or dynamic_categorical_covariates
      or static_numerical_covariates
      or static_categorical_covariates
    ):
      raise ValueError(
        "At least one of dynamic_numerical_covariates,"
        " dynamic_categorical_covariates, static_numerical_covariates,"
        " static_categorical_covariates must be set."
      )

View on GitHub (pinned to 331c6d33cb)

Solutions

Set `return_backcast=True` in the ForecastConfig and call `model.compile()` again
Then call `forecast_with_covariates` with your chosen xreg_mode
If backcast is not needed, switch to a plain `forecast()` call instead of xreg modes

Example fix

// before
config = ForecastConfig(max_context=512, max_horizon=96, return_backcast=False)
model.compile(forecast_config=config)
model.forecast_with_covariates(..., xreg_mode='timesfm + xreg', ...)
// after
config = ForecastConfig(max_context=512, max_horizon=96, return_backcast=True)
model.compile(forecast_config=config)
model.forecast_with_covariates(..., xreg_mode='timesfm + xreg', ...)

Defensive patterns

Strategy: validation

Validate before calling

assert model.forecast_config is not None and model.forecast_config.return_backcast, \
    'Recompile with ForecastConfig(return_backcast=True) before xreg forecasting'

Try / catch

try:
    outputs = model.forecast_with_covariates(..., xreg_mode='timesfm + xreg')
except ValueError as e:
    if 'return_backcast' in str(e):
        model.compile(forecast_config=dataclasses.replace(model.forecast_config, return_backcast=True))
        outputs = model.forecast_with_covariates(..., xreg_mode='timesfm + xreg')
    else:
        raise

Prevention

Use one config builder that sets return_backcast=True whenever xreg modes may be used
Recompile whenever switching between plain and covariate workflows
Keep xreg usage behind a helper that enforces config preconditions

When it happens

Trigger: Calling `forecast_with_covariates(..., xreg_mode='timesfm + xreg')` or `'xreg + timesfm'` after compiling with a ForecastConfig whose `return_backcast` is False or unset; changing to an xreg workflow after a non-xreg compile and not recompiling.

Common situations: Reusing a config originally written for plain forecasting (return_backcast=False) in an xreg pipeline; following older TimesFM 1.x covariate examples where the config flag had a different name/default; toggling xreg_mode at runtime.

Related errors

AI-assisted analysis of google-research/timesfm@331c6d33cb (2026-08-29). Data as JSON: /api/errors/899ae57a1026fe19. Report an issue: GitHub.