Lightning-AI/pytorch-lightning · error · TypeError

To spawn processes with the `{type(self.strategy).name}`

Error message

To spawn processes with the `{type(self.strategy).__name__}` strategy, `.launch()` needs to be called with a function that contains the code to launch in processes.

What it means

Strategies that spawn processes (via _MultiProcessingLauncher or _XLALauncher, e.g. ddp_spawn, XLA/TPU) need the code to run in child processes supplied as a function to .launch(). If function is _do_nothing (nothing passed) and the strategy uses a spawning launcher, Fabric cannot pickle/spawn anything, so it raises TypeError.

Source

Thrown at src/lightning/fabric/fabric.py:1006

        """
        if _is_using_cli():
            raise RuntimeError(
                "This script was launched through the CLI, and processes have already been created. Calling "
                " `.launch()` again is not allowed."
            )
        if function is not _do_nothing:
            if not callable(function):
                raise TypeError(
                    f"`Fabric.launch(...)` needs to be a callable, but got {function}."
                    " HINT: do `.launch(your_fn)` instead of `.launch(your_fn())`"
                )
            if not inspect.signature(function).parameters:
                raise TypeError(
                    f"`Fabric.launch(function={function})` needs to take at least one argument. The launcher will"
                    " pass in the `Fabric` object so you can use it inside the function."
                )
        elif isinstance(self.strategy.launcher, (_MultiProcessingLauncher, _XLALauncher)):
            raise TypeError(
                f"To spawn processes with the `{type(self.strategy).__name__}` strategy, `.launch()` needs to be called"
                " with a function that contains the code to launch in processes."
            )
        return self._wrap_and_launch(function, self, *args, **kwargs)

    def _filter_kwargs_for_callback(self, method: Callable, kwargs: dict[str, Any]) -> dict[str, Any]:
        """Filter keyword arguments to only include those that match the callback method's signature.

        Args:
            method: The callback method to inspect
            kwargs: The keyword arguments to filter

        Returns:
            A filtered dictionary of keyword arguments that match the method's signature

        """
        try:
            sig = inspect.signature(method)

View on GitHub (pinned to 9fed5c27d2)

Solutions

Wrap your training code in a function and call fabric.launch(train) first
Or switch to a non-spawning strategy: strategy='ddp' so setup works without a spawned function

Example fix

# before
fabric = Fabric(strategy='ddp_spawn', devices=2)
model = fabric.setup(model)
# after
fabric = Fabric(strategy='ddp_spawn', devices=2)
def train(fabric):
    model = fabric.setup(model)
fabric.launch(train)

Defensive patterns

Strategy: fallback

Validate before calling

from lightning.fabric.plugins.collective import _MultiProcessingLauncher
if fabric.strategy.launcher is not None and 'spawn' in type(fabric.strategy.launcher).__name__.lower():
    raise SystemExit('spawn strategies require .launch(fn) with your training code')

Prevention

For spawn-based strategies (ddp_spawn, xla), always structure code as a launched function
Prefer non-spawn strategies (ddp) for simpler setups

When it happens

Trigger: Creating Fabric(strategy='ddp_spawn', devices=2) and never calling fabric.launch(fn) — e.g. going straight to fabric.setup(model), whose validation path requires the launch for spawn strategies.

Common situations: Switching a single-device script to ddp_spawn/XLA without adding .launch(); calling setup inside a helper that skips the launch branch.

Related errors

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