troubleshooting-common-errors

Troubleshooting Common Errors

This skill is the full pitfall catalog. The highest-risk skills also carry a focused ## Stop Conditions table at the top (forecasting-single-series, forecasting-multiple-series, prediction-intervals, statistical-models, foundation-forecasting, feature-engineering, deep-learning-forecasting, hyperparameter-optimization); this skill remains the canonical source they point back to.

Deprecated Import Paths

The most frequent LLM error. Old import paths no longer exist.

Wrong Class/Function Names

Removed Arguments

Categorical Exogenous Variables

# ❌ WRONG: setting categorical features directly on the estimator
forecaster = ForecasterRecursive(
    estimator=LGBMRegressor(categorical_feature=[0, 1]),
    lags=24,
)

# ✅ CORRECT: use categorical_features parameter on the forecaster
forecaster = ForecasterRecursive(
    estimator=LGBMRegressor(),
    lags=24,
    categorical_features='auto',  # or ['col_name_1', 'col_name_2']
)

Data Issues

"ValueError: The index of the series must be a DatetimeIndex with frequency"

# Fix: set the frequency
data = data.asfreq('h')       # Hourly
data = data.asfreq('D')       # Daily
data = data.asfreq('MS')      # Monthly start
data = data.asfreq('QS')      # Quarterly start

"ValueError: y contains NaN values"

# Fix 1 (recommended for NaN-tolerant estimators): keep NaN rows
forecaster = ForecasterRecursive(
    estimator=LGBMRegressor(verbose=-1),  # LightGBM handles NaN natively
    lags=14,
    dropna_from_series=False,  # Default — NaN rows kept in training matrices
)
forecaster.fit(y=data['target'], suppress_warnings=True)

# Fix 2: drop rows with NaN from training matrices
forecaster = ForecasterRecursive(
    estimator=RandomForestRegressor(),
    lags=14,
    dropna_from_series=True,  # Drop NaN rows before fitting
)

# Fix 3: impute missing values before fitting
data = data.ffill()                      # Forward fill
data = data.interpolate(method='linear') # Linear interpolation

"ValueError: exog must have the same index as y" / "exog does not cover forecast horizon"

# Fix: exog for prediction must cover ALL future steps
# If predicting 10 steps ahead, exog_test must have at least 10 rows
# with dates matching the expected forecast dates
exog_test = exog.loc[forecast_start:forecast_end]
predictions = forecaster.predict(steps=10, exog=exog_test)

Wrong Backtesting Function

# ❌ WRONG: using backtesting_forecaster with ForecasterStats
from skforecast.model_selection import backtesting_forecaster
backtesting_forecaster(forecaster=forecaster_stats, y=y, cv=cv, metric=metric)  # Error!

# ✅ CORRECT: use backtesting_stats for statistical models
from skforecast.model_selection import backtesting_stats
backtesting_stats(forecaster=forecaster_stats, y=y, cv=cv, metric=metric)

# ❌ WRONG: using backtesting_forecaster with ForecasterRecursiveMultiSeries
backtesting_forecaster(forecaster=forecaster_multi, y=y, cv=cv, metric=metric)  # Error!

# ✅ CORRECT: use backtesting_forecaster_multiseries
from skforecast.model_selection import backtesting_forecaster_multiseries
backtesting_forecaster_multiseries(
    forecaster=forecaster_multi, series=series, cv=cv, metric=metric
)

Wrong Search Function

# ❌ WRONG: grid_search_forecaster with ForecasterStats
grid_search_forecaster(forecaster=forecaster_stats, y=y, cv=cv, param_grid=param_grid)

# ✅ CORRECT: grid_search_stats for statistical models
from skforecast.model_selection import grid_search_stats
grid_search_stats(forecaster=forecaster_stats, y=y, cv=cv, param_grid=param_grid)

# ❌ WRONG: grid_search_forecaster with ForecasterRecursiveMultiSeries
grid_search_forecaster(forecaster=forecaster_multi, y=y, cv=cv, param_grid=param_grid)

# ✅ CORRECT: grid_search_forecaster_multiseries
from skforecast.model_selection import grid_search_forecaster_multiseries
grid_search_forecaster_multiseries(
    forecaster=forecaster_multi, series=series, cv=cv, param_grid=param_grid
)

Prediction Interval Errors

"No in-sample residuals stored"

# ❌ WRONG: fit without residuals, then call predict_interval
forecaster.fit(y=y_train)
forecaster.predict_interval(steps=10, method='bootstrapping')

# ✅ CORRECT: store residuals during fit
forecaster.fit(y=y_train, store_in_sample_residuals=True)
forecaster.predict_interval(steps=10, method='bootstrapping')

Wrong interval method for a forecaster

ETS Model API Confusion

# ❌ WRONG (deprecated Ets API)
ets_model = Ets(error='add', trend='add', seasonal='add', seasonal_periods=12)

# ✅ CORRECT (current API)
ets_model = Ets(model='AAA', m=12)
# Model string: 1st char=Error, 2nd=Trend, 3rd=Seasonal
# A=Additive, M=Multiplicative, N=None, Z=Auto-select

Function Mapping Reference

Loading Serialized Forecasters from Older Versions

Forecasters saved (pickled/joblib) with older skforecast versions may fail to load or behave unexpectedly after upgrading. Internal attributes, class structures, and default values change between releases.

# ❌ Common error when loading a forecaster saved with an older version
import joblib
forecaster = joblib.load('forecaster_v0.13.pkl')
# AttributeError: 'ForecasterRecursive' object has no attribute 'new_attribute'
# or: ModuleNotFoundError: No module named 'skforecast.ForecasterAutoreg'

# ✅ CORRECT: retrain the forecaster with the current version
forecaster = ForecasterRecursive(
    estimator=LGBMRegressor(),
    lags=24,
)
forecaster.fit(y=y_train)
joblib.dump(forecaster, 'forecaster_v0.22.pkl')

Best practices:

• Always retrain and re-save forecasters after upgrading skforecast.
• Store training code (not just the serialized object) so models can be reproduced.
• Pin skforecast version in requirements.txt for production deployments.