Lightning-AI / Lightning-AI/pytorch-lightning

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

Open
#20,851 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug lightningcli ver: 2.5.x
Dominant language
Python
Stars
31.4k
Forks
3.8k
Avg merge
6d 7h
Merged PRs (30d)
6

Description

### 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`](https://github.com/Lightning-AI/pytorch-lightning/blob/dd2912a045f1a1a0c87528b41c9854fc7454d4b0/src/lightning/pytorch/cli.py#L150
) as is the default. Simple example to reproduce:

```python
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](https://github.com/Lightning-AI/pytorch-lightning/blob/dd2912a045f1a1a0c87528b41c9854fc7454d4b0/src/lightning/pytorch/cli.py#L150), namely `jsonargparse.ArgumentParser`, and [that does not seem to support a `required` argument](https://github.com/omni-us/jsonargparse/blob/dcd0a5ae70d0ef5c7c053436375bcad9aa462c84/jsonargparse/_signatures.py#L46).

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

```python

```

### 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_

cc @mauvilsa

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in src/lightning/pytorch/cli.py at add_lightning_class_args and compare the superclass call with jsonargparse's _signatures.py, both linked in the report. Reproduce the FooCheckpoint example with subclass_mode=False and required=False; done means the omitted checkpoint argument is accepted without the reported validation error, with behavior covered by regression testing.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.