Lightning-AI/pytorch-lightning · error · MisconfigurationException

Found invalid type for plugin {plugin}. Expected one of: Pre

Error message

Found invalid type for plugin {plugin}. Expected one of: Precision, CheckpointIO, ClusterEnvironment, or LayerSync.

What it means

The Trainer's `plugins` argument only accepts instances of Precision, CheckpointIO, ClusterEnvironment, or LayerSync (e.g. TorchSyncBatchNorm). AcceleratorConnector's config validation rejects any other object type passed in the plugins list. This is a strict type whitelist enforced in _check_config_and_set_final_flags.

Source

Thrown at src/lightning/pytorch/trainer/connectors/accelerator_connector.py:247

                if isinstance(plugin, Precision):
                    self._precision_plugin_flag = plugin
                    plugins_flags_types[Precision.__name__] += 1
                elif isinstance(plugin, CheckpointIO):
                    self.checkpoint_io = plugin
                    plugins_flags_types[CheckpointIO.__name__] += 1
                elif isinstance(plugin, ClusterEnvironment):
                    self._cluster_environment_flag = plugin
                    plugins_flags_types[ClusterEnvironment.__name__] += 1
                elif isinstance(plugin, LayerSync):
                    if sync_batchnorm and not isinstance(plugin, TorchSyncBatchNorm):
                        raise MisconfigurationException(
                            f"You set `Trainer(sync_batchnorm=True)` and provided a `{plugin.__class__.__name__}`"
                            " plugin, but this is not allowed. Choose one or the other."
                        )
                    self._layer_sync = plugin
                    plugins_flags_types[TorchSyncBatchNorm.__name__] += 1
                else:
                    raise MisconfigurationException(
                        f"Found invalid type for plugin {plugin}. Expected one of: Precision, "
                        "CheckpointIO, ClusterEnvironment, or LayerSync."
                    )

            duplicated_plugin_key = [k for k, v in plugins_flags_types.items() if v > 1]
            if duplicated_plugin_key:
                raise MisconfigurationException(
                    f"Received multiple values for {', '.join(duplicated_plugin_key)} flags in `plugins`."
                    " Expected one value for each type at most."
                )

            if plugins_flags_types.get(Precision.__name__) and precision_flag is not None:
                raise ValueError(
                    f"Received both `precision={precision_flag}` and `plugins={self._precision_plugin_flag}`."
                    f" Choose one."
                )

        self._precision_flag = "32-true" if precision_flag is None else precision_flag

View on GitHub (pinned to 9fed5c27d2)

Solutions

Remove the invalid object from the `plugins` list and pass it via its dedicated Trainer argument (strategy=, accelerator=, callbacks=)
If it is a custom precision/io/cluster/sync plugin, subclass the corresponding base class (Precision, CheckpointIO, ClusterEnvironment, LayerSync)
Check for leftover deprecated plugin names from Lightning 1.x after upgrading

Example fix

# before
trainer = Trainer(plugins=[DDPStrategy()])
# after
trainer = Trainer(strategy=DDPStrategy())

Defensive patterns

Strategy: validation

Validate before calling

from lightning.pytorch.plugins import Precision, CheckpointIO, ClusterEnvironment, LayerSync
_ALLOWED = (Precision, CheckpointIO, ClusterEnvironment, LayerSync)
plugins = [p for p in plugins if isinstance(p, _ALLOWED)]
trainer = Trainer(plugins=plugins)

Type guard

from lightning.pytorch.plugins import Precision, CheckpointIO, ClusterEnvironment, LayerSync
def is_valid_plugin(p: object) -> bool:
    return isinstance(p, (Precision, CheckpointIO, ClusterEnvironment, LayerSync))

Try / catch

from lightning.pytorch.utilities.exceptions import MisconfigurationException
try:
    trainer = Trainer(plugins=plugins)
except MisconfigurationException as e:
    if "invalid type for plugin" in str(e):
        plugins = [p for p in plugins if is_valid_plugin(p)]
        trainer = Trainer(plugins=plugins)
    else:
        raise

Prevention

Keep a single helper that builds the plugins list and validates types
Pass strategies via strategy=, accelerators via accelerator=, never via plugins

When it happens

Trigger: Passing Trainer(plugins=[SomeObject()]) where SomeObject is not a Precision/CheckpointIO/ClusterEnvironment/LayerSync instance, e.g. a Strategy, Accelerator, callback, or arbitrary object in the plugins list.

Common situations: Developers migrate from older Lightning versions where more plugin types were accepted, or confuse `plugins` with `strategy`, `accelerators`, or `callbacks` Trainer arguments.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

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