Lightning-AI/pytorch-lightning · error · MisconfigurationException

`{self.class.name}.add_configure_optimizers_method_t

Error message

`{self.__class__.__name__}.add_configure_optimizers_method_to_model` expects at most one optimizer and one lr_scheduler to be 'AUTOMATIC', but found {optimizers + lr_schedulers}. In this case the user is expected to link the argument groups and implement `configure_optimizers`, see https://lightning.ai/docs/pytorch/stable/common/lightning_cli.html#optimizers-and-learning-rate-schedulers

What it means

LightningCLI can auto-implement configure_optimizers only when at most one optimizer and one lr_scheduler argument group is left as AUTOMATIC. During instantiate_classes -> add_configure_optimizers_method_to_model, if both counts exceed the limit (their combined list is non-empty beyond the single allowance) it raises this MisconfigurationException telling the user to link groups and implement configure_optimizers manually.

Source

Thrown at src/lightning/pytorch/cli.py:710

        def get_automatic(
            class_type: Union[type, tuple[type, ...]], register: dict[str, tuple[Union[type, tuple[type, ...]], str]]
        ) -> list[str]:
            automatic = []
            for key, (base_class, link_to) in register.items():
                if not isinstance(base_class, tuple):
                    base_class = (base_class,)
                if link_to == "AUTOMATIC" and any(issubclass(c, class_type) for c in base_class):
                    automatic.append(key)
            return automatic

        optimizers = get_automatic(Optimizer, parser._optimizers)
        lr_schedulers = get_automatic(LRSchedulerTypeTuple, parser._lr_schedulers)

        if len(optimizers) == 0:
            return

        if len(optimizers) > 1 or len(lr_schedulers) > 1:
            raise MisconfigurationException(
                f"`{self.__class__.__name__}.add_configure_optimizers_method_to_model` expects at most one optimizer "
                f"and one lr_scheduler to be 'AUTOMATIC', but found {optimizers + lr_schedulers}. In this case the "
                "user is expected to link the argument groups and implement `configure_optimizers`, see "
                "https://lightning.ai/docs/pytorch/stable/common/lightning_cli.html"
                "#optimizers-and-learning-rate-schedulers"
            )

        optimizer_class = parser._optimizers[optimizers[0]][0]
        optimizer_init = self._get(self.config_init, optimizers[0])
        if not isinstance(optimizer_class, tuple):
            optimizer_init = _global_add_class_path(optimizer_class, optimizer_init)
        if not optimizer_init:
            # optimizers were registered automatically but not passed by the user
            return

        lr_scheduler_init = None
        if lr_schedulers:
            lr_scheduler_class = parser._lr_schedulers[lr_schedulers[0]][0]

View on GitHub (pinned to 9fed5c27d2)

Solutions

Implement configure_optimizers manually on the LightningModule and link groups in the config (use --optimizer.link_a.b etc. per the linked docs)
Reduce to one optimizer + one scheduler so AUTOMATIC mode can generate configure_optimizers
Pass subclass_args so optimizer groups aren't all AUTOMATIC

Example fix

# before
# cli command with two automatic optimizers -> MisconfigurationException
# lightning run train --optimizer=Adam --optimizer.lr_scheduler=CosineAnnealingLR --optimizer2=SGD ...
# after
# in model:
def configure_optimizers(self):
    opt1 = torch.optim.Adam(self.enc.parameters())
    opt2 = torch.optim.SGD(self.dec.parameters(), lr=0.01)
    return [opt1, opt2], []
# and configure cli with linked/manual groups instead of AUTOMATIC

Defensive patterns

Strategy: validation

Validate before calling

def configure_optimizers(self):
    # manual wiring when using multiple optimizers via CLI
    enc_opt = self.hparams.optimizer_enc(self.parameters('enc'))
    dec_opt = self.hparams.optimizer_dec(self.parameters('dec'))
    return [enc_opt, dec_opt], []

Prevention

For multi-optimizer models, implement configure_optimizers yourself and link CLI groups
Keep AUTOMATIC mode to one optimizer + one scheduler

When it happens

Trigger: CLI config with two optimizers (e.g. --optimizer.class=torch.optim.Adam plus another linked optimizer group, or optimizer + optimizer.lr_scheduler combos) all left AUTOMATIC so len(optimizers)+len(lr_schedulers) > allowed.

Common situations: Multi-optimizer GAN-style models configured entirely via CLI; users adding --lr_scheduler alongside two optimizer groups expecting LightningCLI to wire them automatically.

Related errors

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