Lightning-AI/pytorch-lightning · error · MisconfigurationException

`return_predictions` should be set to `False` when using the

Error message

`return_predictions` should be set to `False` when using the strategies that spawn or fork. Found {return_predictions} with strategy {type(self.trainer.strategy)}.

What it means

Raised by the prediction loop's return_predictions setter when return_predictions is truthy and the strategy uses a subprocess launcher (_MultiProcessingLauncher, e.g. ddp_spawn or Colab/Boulder fork-based strategies). Spawned/forked worker processes cannot reliably send collected predictions back to the main process, so returning them is disallowed.

Source

Thrown at src/lightning/pytorch/loops/prediction_loop.py:78

        self._data_source = _DataLoaderSource(None, "predict_dataloader")
        self._combined_loader: Optional[CombinedLoader] = None
        self._data_fetcher: Optional[_DataFetcher] = None
        self._results = None  # for `trainer._results` access
        self._predictions: list[list[Any]] = []  # dataloaders x batches
        self._return_predictions = False
        self._module_mode = _ModuleMode()

    @property
    def return_predictions(self) -> bool:
        """Whether to return the predictions or not."""
        return self._return_predictions

    @return_predictions.setter
    def return_predictions(self, return_predictions: Optional[bool] = None) -> None:
        # Strategies that spawn or fork don't support returning predictions
        return_supported = not isinstance(self.trainer.strategy.launcher, _MultiProcessingLauncher)
        if return_predictions and not return_supported:
            raise MisconfigurationException(
                "`return_predictions` should be set to `False` when using the strategies that spawn or fork."
                f" Found {return_predictions} with strategy {type(self.trainer.strategy)}."
            )
        # For strategies that support it, `return_predictions` is True by default unless user decide otherwise.
        self._return_predictions = return_supported if return_predictions is None else return_predictions

    @property
    def predictions(self) -> list[Any]:
        """The cached predictions."""
        if self._predictions == []:
            return self._predictions
        return self._predictions[0] if self.num_dataloaders == 1 else self._predictions

    @property
    def num_dataloaders(self) -> int:
        """Returns the number of prediction dataloaders."""
        combined_loader = self._combined_loader
        assert combined_loader is not None

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Pass `return_predictions=False` and collect results via a prediction callback writing to disk
2. Or switch to a non-spawning strategy like 'ddp' for prediction
3. Write predictions inside predict_step or on_predict_epoch_end instead of returning them

Example fix

# before
trainer = pl.Trainer(strategy='ddp_spawn', devices=2)
preds = trainer.predict(model, dataloaders=dl)  # default return_predictions=True

# after
trainer = pl.Trainer(strategy='ddp_spawn', devices=2)
trainer.predict(model, dataloaders=dl, return_predictions=False)  # gather via callback

from lightning.pytorch.strategies.launchers import _MultiProcessingLauncher

if isinstance(trainer.strategy.launcher, _MultiProcessingLauncher):
    return_predictions = False
trainer.predict(model, dl, return_predictions=return_predictions)

def can_return_predictions(trainer) -> bool:
    return not isinstance(trainer.strategy.launcher, _MultiProcessingLauncher)

When it happens

Trigger: `Trainer(strategy='ddp_spawn', devices=2)` with `trainer.predict(model, return_predictions=True)` (or relying on the True default); any launcher that spawns/forks processes combined with predict.

Common situations: Switching a prediction script from single-process to ddp_spawn for multi-GPU inference; notebook environments where spawn strategies are common defaults.

Related errors

• `trainer.predict()` only supports the `CombinedLoader(mode="
• `Trainer.predict()` requires a `LightningModule` when it has
• You cannot pass both `trainer.predict(dataloaders=..., datam
• Device should be CPU, got {device} instead.
• `devices` selected with `CPUAccelerator` should be an int >

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/1f84c64401a51385. Report an issue: GitHub.