• Import errors for optional packages
• Shape mismatch in the direct forecasting path
• Shape mismatch in seq2seq or transformer workflows
• TimeSeriesHandler.transform(...) does not work on a fresh instance
• Mixed precision causes issues on CPU or during debugging

Troubleshooting

This page collects the most common first-run issues for foreblocks.

Import errors for optional packages

Some subsystems require optional extras that are not part of the base install.

Symptom	Likely fix
Plotting helpers complain about matplotlib	pip install "foreblocks[plotting]"
TimeSeriesHandler or preprocessing utilities fail to import scientific packages	pip install "foreblocks[preprocessing]"
DARTS trainer, analyzer, or search visuals fail to import	pip install "foreblocks[darts]"
MLTracker API or UI modules fail to import	pip install "foreblocks[mltracker]"
VMD utilities or Optuna search features fail to import	pip install "foreblocks[vmd]"
Wavelet-related blocks are unavailable	pip install "foreblocks[wavelets]"
External benchmark integrations fail to import	pip install "foreblocks[benchmark]"
Changepoint-detection helpers are unavailable	pip install "foreblocks[foreminer]"

If you want every optional runtime dependency:

pip install "foreblocks[all]"

Shape mismatch in the direct forecasting path

The simplest path expects:

• X: [N, T, F]
• direct head output: same shape as the target tensor

If your head returns [N, horizon], your y should also be [N, horizon].

Shape mismatch in seq2seq or transformer workflows

Most encoder/decoder workflows use:

• inputs: [N, T, F]
• targets: [N, H, D]

If you are building custom encoder or decoder blocks, verify the hidden size, target horizon, and feature dimension contracts before debugging the training loop.

Relevant guides:

• Custom Blocks Guide
• Transformer Guide

TimeSeriesHandler.transform(...) does not work on a fresh instance

transform(...) uses fitted preprocessing state.

The normal order is:

pre = TimeSeriesHandler(window_size=24, horizon=6)
X_train, y_train, processed, time_feat = pre.fit_transform(train_data)
X_val = pre.transform(val_data)

This is especially important when normalization, differencing, or detrending is enabled.

Mixed precision causes issues on CPU or during debugging

For small local runs and debugging sessions, prefer:

config = TrainingConfig(use_amp=False)

Then run:

npm run docs:dev