{"record":{"id":"899ae57a1026fe19","repo":"google-research/timesfm","slug":"for-xreg-return-backcast-must-be-set-to-true-in","errorCode":null,"errorMessage":"For XReg, `return_backcast` must be set to True in the forecast config. Please recompile the model.","messagePattern":"For XReg, `return_backcast` must be set to True in the forecast config\\. Please recompile the model\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/timesfm/timesfm_2p5/timesfm_2p5_base.py","lineNumber":241,"sourceCode":"      static_categorical_covariates: A dict of static categorical covariates.\n      xreg_mode: one of \"xreg + timesfm\" or \"timesfm + xreg\". \"xreg + timesfm\"\n        first fits an XReg model on the targets, then uses TimesFM to forecast\n        the residuals. \"timesfm + xreg\" first runs TimesFM to get a forecast,\n        then fits an XReg model on the residuals of that forecast.\n      normalize_xreg_target_per_input: whether to normalize the xreg target per\n        input in the given batch.\n      ridge: ridge penalty for the linear model.\n      max_rows_per_col: max number of rows per column for the linear model.\n      force_on_cpu: whether to force running on cpu for the linear model.\n\n    Returns:\n      A tuple of two lists. The first is the outputs of the model. The second is\n      the outputs of the xreg.\n    \"\"\"\n    if self.forecast_config is None:\n      raise ValueError(\"Model is not compiled. Please call compile() first.\")\n    elif not self.forecast_config.return_backcast:\n      raise ValueError(\n        \"For XReg, `return_backcast` must be set to True in the forecast config. Please recompile the model.\"\n      )\n\n    from ..utils import xreg_lib\n\n    # Verify and bookkeep covariates.\n    if not (\n      dynamic_numerical_covariates\n      or dynamic_categorical_covariates\n      or static_numerical_covariates\n      or static_categorical_covariates\n    ):\n      raise ValueError(\n        \"At least one of dynamic_numerical_covariates,\"\n        \" dynamic_categorical_covariates, static_numerical_covariates,\"\n        \" static_categorical_covariates must be set.\"\n      )\n","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/google-research/timesfm/blob/331c6d33cb1ac2611de3056d0ac7164aab6301eb/src/timesfm/timesfm_2p5/timesfm_2p5_base.py#L223-L259","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nconfig = ForecastConfig(max_context=512, max_horizon=96, return_backcast=False)\nmodel.compile(forecast_config=config)\nmodel.forecast_with_covariates(..., xreg_mode='timesfm + xreg', ...)\n// after\nconfig = ForecastConfig(max_context=512, max_horizon=96, return_backcast=True)\nmodel.compile(forecast_config=config)\nmodel.forecast_with_covariates(..., xreg_mode='timesfm + xreg', ...)","handlingStrategy":"validation","validationCode":"assert model.forecast_config is not None and model.forecast_config.return_backcast, \\\n    'Recompile with ForecastConfig(return_backcast=True) before xreg forecasting'","typeGuard":null,"tryCatchPattern":"try:\n    outputs = model.forecast_with_covariates(..., xreg_mode='timesfm + xreg')\nexcept ValueError as e:\n    if 'return_backcast' in str(e):\n        model.compile(forecast_config=dataclasses.replace(model.forecast_config, return_backcast=True))\n        outputs = model.forecast_with_covariates(..., xreg_mode='timesfm + xreg')\n    else:\n        raise","preventionTips":["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"],"tags":["python","config-mismatch","covariates","xreg"],"backgroundTag":"config-flag-mismatch","analyzedSha":"331c6d33cb1ac2611de3056d0ac7164aab6301eb","analyzedAt":"2026-08-29T01:04:23.138Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}