`add_lightning_class_args` `required` argument ignored if not using subclass mode

[kylebgorman]

Bug description

LightningCLI's method add_lightning_class_args has an optional argument required which defaults to True. According to the documentation, when required=True, the user must specify the callback/class (or it must be default-constructable); when required=False it need not be. However, the required argument is ignored when subclass_mode=False as is the default. Simple example to reproduce:

from lightning.pytorch import callbacks, cli

class FooCheckpoint(callbacks.ModelCheckpoint):

    # Makes one argument required so it can't be default-constructed.
    def __init__(self, dirpath, *args, **kwargs):
        super().__init__(dirpath, *args, **kwargs)


class FooCLI(cli.LightningCLI):
    def add_arguments_to_parser(
        self, parser: cli.LightningArgumentParser
    ) -> None:
        parser.add_lightning_class_args(
            FooCheckpoint,
            "checkpoint",
            required=False,
        )

Attempting to instantiate FooCLI with any choice of model and datamodule but without specify the checkpoint's required argument will result in a configuration error:

Validation failed: Key "fit.checkpoint.dirpath" is required but not included in config object or its value is None.

I don't have the full context but the fix may be non-trivial in that when subclass_mode=False, LightningCLI calls add_class_arguments from the superclass, namely jsonargparse.ArgumentParser, and that does not seem to support a required argument.

At the very least though the documentation should probably be modified to explain that required=True is ignored unless subclass_mode=True.

What version are you seeing the problem on?

v2.5

Reproduced in studio

No response

How to reproduce the bug

Error messages and logs

Validation failed: Key "fit.checkpoint.dirpath" is required but not included in config object or its value is None.

Environment

Current environment

• CUDA: - GPU: - NVIDIA GeForce GTX 1660 Ti - available: True - version: 12.4
• Lightning: - lightning: 2.5.0.post0 - lightning-cloud: 0.5.70 - lightning-utilities: 0.14.3 - pytorch-lightning: 2.5.0.post0 - torch: 2.5.1 - torchmetrics: 1.7.1
• Packages: - accelerate: 1.7.0 - aiohappyeyeballs: 2.6.1 - aiohttp: 3.11.18 - aiosignal: 1.3.2 - anyio: 4.9.0 - arrow: 1.3.0 - asttokens: 3.0.0 - attrs: 25.3.0 - autocommand: 2.2.2 - backports.tarfile: 1.2.0 - beautifulsoup4: 4.13.4 - black: 24.10.0 - blessed: 1.21.0 - boto3: 1.38.18 - botocore: 1.38.18 - certifi: 2025.4.26 - charset-normalizer: 3.4.2 - click: 8.2.0 - croniter: 1.3.15 - dateutils: 0.6.12 - decorator: 5.1.1 - deepdiff: 7.0.1 - deprecated: 1.2.13 - docker-pycreds: 0.4.0 - docstring-parser: 0.16 - editor: 1.6.6 - executing: 0.8.3 - fastapi: 0.88.0 - filelock: 3.18.0 - flake8: 7.1.1 - frozenlist: 1.6.0 - fsspec: 2023.12.2 - gitdb: 4.0.12 - gitpython: 3.1.44 - h11: 0.16.0 - hf-xet: 1.1.2 - huggingface-hub: 0.31.2 - idna: 3.10 - importlib-metadata: 8.5.0 - importlib-resources: 6.5.2 - inflect: 7.3.1 - inquirer: 3.4.0 - ipython: 9.1.0 - ipython-pygments-lexers: 1.1.1 - itsdangerous: 2.2.0 - jaraco.collections: 5.1.0 - jaraco.context: 5.3.0 - jaraco.functools: 4.0.1 - jaraco.text: 3.12.1 - jedi: 0.19.2 - jinja2: 3.1.6 - jmespath: 1.0.1 - jsonargparse: 4.40.0 - lightning: 2.5.0.post0 - lightning-cloud: 0.5.70 - lightning-utilities: 0.14.3 - lit: 17.0.6.dev0 - markdown-it-py: 3.0.0 - markupsafe: 3.0.2 - matplotlib-inline: 0.1.6 - maxwell: 0.2.6 - mccabe: 0.7.0 - mdurl: 0.1.2 - mkl-service: 2.4.0 - more-itertools: 10.3.0 - mpmath: 1.3.0 - multidict: 6.4.3 - mypy-extensions: 1.0.0 - networkx: 3.4.2 - numpy: 2.2.6 - nvidia-cublas-cu12: 12.4.5.8 - nvidia-cuda-cupti-cu12: 12.4.127 - nvidia-cuda-nvrtc-cu12: 12.4.127 - nvidia-cuda-runtime-cu12: 12.4.127 - nvidia-cudnn-cu12: 9.1.0.70 - nvidia-cufft-cu12: 11.2.1.3 - nvidia-curand-cu12: 10.3.5.147 - nvidia-cusolver-cu12: 11.6.1.9 - nvidia-cusparse-cu12: 12.3.1.170 - nvidia-nccl-cu12: 2.21.5 - nvidia-nvjitlink-cu12: 12.4.127 - nvidia-nvtx-cu12: 12.4.127 - opentelemetry-api: 1.30.0 - ordered-set: 4.1.0 - packaging: 24.2 - parso: 0.8.4 - pathspec: 0.10.3 - pexpect: 4.8.0 - pip: 25.1 - platformdirs: 4.3.8 - prompt-toolkit: 3.0.43 - propcache: 0.3.1 - protobuf: 5.29.4 - psutil: 6.1.1 - ptyprocess: 0.7.0 - pure-eval: 0.2.2 - pycodestyle: 2.12.1 - pydantic: 1.10.22 - pyflakes: 3.2.0 - pygments: 2.19.1 - pyjwt: 2.10.1 - python-dateutil: 2.9.0.post0 - python-multipart: 0.0.20 - pytorch-lightning: 2.5.0.post0 - pytz: 2025.2 - pyyaml: 6.0.2 - readchar: 4.2.1 - regex: 2024.11.6 - requests: 2.32.3 - rich: 14.0.0 - runs: 1.2.2 - s3transfer: 0.12.0 - safetensors: 0.5.3 - sentry-sdk: 2.28.0 - setproctitle: 1.3.6 - setuptools: 78.1.1 - six: 1.17.0 - smmap: 5.0.2 - sniffio: 1.3.1 - soupsieve: 2.7 - stack-data: 0.2.0 - starlette: 0.22.0 - starsessions: 1.3.0 - sympy: 1.13.1 - tokenizers: 0.21.1 - tomli: 2.0.1 - torch: 2.5.1 - torchmetrics: 1.7.1 - tqdm: 4.67.1 - traitlets: 5.14.3 - transformers: 4.51.3 - triton: 3.1.0 - typeguard: 4.3.0 - types-python-dateutil: 2.9.0.20250516 - typeshed-client: 2.7.0 - typing-extensions: 4.12.2 - urllib3: 2.4.0 - uvicorn: 0.34.2 - wandb: 0.18.7 - wcwidth: 0.2.13 - websocket-client: 1.8.0 - websockets: 11.0.3 - wheel: 0.45.1 - wrapt: 1.17.0 - xmod: 1.8.1 - yarl: 1.20.0 - yoyodyne: 0.3.2 - yoyodyne-pretrained: 0.1.0 - zipp: 3.21.0
• System: - OS: Linux - architecture: - 64bit - ELF - processor: x86_64 - python: 3.13.2 - release: 5.15.167.4-microsoft-standard-WSL2 - version: #1 SMP Tue Nov 5 00:21:55 UTC 2024

More info

No response

[KAVYANSHTYAGI]

Summary

LightningCLI's method add_lightning_class_args exposes a required parameter which is ignored when subclass_mode=False (the default), contradicting the documented behavior. The documentation claims that setting required=False should make providing the argument optional, but in practice, jsonargparse.ArgumentParser which is used under the hood does not honor the required argument unless subclass_mode=True.

Root Cause

The required argument is only respected when subclass_mode=True, as jsonargparse's add_class_arguments (called when subclass_mode=False) does not utilize the required flag.

[stale[bot]]

This issue has been automatically marked as stale because it hasn't had any recent activity. This issue will be closed in 7 days if no further activity occurs. Thank you for your contributions - the Lightning Team!

[mauvilsa]

@KAVYANSHTYAGI unfortunately the presence of the required parameter mislead you. The only reason why add_lightning_class_args supports Callback is to add callbacks that must always be present, see configure-forced-callbacks in the docs. So simply Callback + required=False should give an error.