{"record":{"id":"085aeb638ca36345","repo":"Lightning-AI/pytorch-lightning","slug":"deepspeedstrategy-save-checkpoint-filter","errorCode":null,"errorMessage":"`DeepSpeedStrategy.save_checkpoint(..., filter=...)` is not supported because `DeepSpeedStrategy` manages the state serialization internally.","messagePattern":"`DeepSpeedStrategy\\.save_checkpoint\\(\\.\\.\\., filter=\\.\\.\\.\\)` is not supported because `DeepSpeedStrategy` manages the state serialization internally\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/strategies/deepspeed.py","lineNumber":436,"sourceCode":"                state-dict will be retrieved and converted automatically.\n            storage_options: Unused by this strategy, since it doesn't use a ``CheckpointIO`` plugin.\n            filter: Unsupported.\n\n        Raises:\n            TypeError:\n                If the unused ``storage_options`` gets passed.\n            ValueError:\n                When no :class:`deepspeed.DeepSpeedEngine` objects were found in the state, or when multiple\n                :class:`deepspeed.DeepSpeedEngine` objects were found.\n\n        \"\"\"\n        if storage_options is not None:\n            raise TypeError(\n                \"`DeepSpeedStrategy.save_checkpoint(..., storage_options=...)` is not supported because\"\n                \" `DeepSpeedStrategy` does not use the `CheckpointIO`.\"\n            )\n        if filter is not None:\n            raise TypeError(\n                \"`DeepSpeedStrategy.save_checkpoint(..., filter=...)` is not supported because\"\n                \" `DeepSpeedStrategy` manages the state serialization internally.\"\n            )\n\n        engines = _get_deepspeed_engines_from_state(state)\n        if len(engines) == 0:\n            raise ValueError(\n                \"Could not find a DeepSpeed model in the provided checkpoint state. Please provide the model as\"\n                \" part of the state like so: `save_checkpoint(..., state={'model': model, ...})`. Make sure\"\n                \" you set up the model (and optimizers if any) through the strategy before saving the checkpoint.\"\n            )\n        if len(engines) > 1:\n            raise ValueError(\n                \"Found multiple DeepSpeed engine modules in the given state. Saving checkpoints with DeepSpeed is\"\n                \" currently limited to a single model per checkpoint. To save multiple models, call the\"\n                \" save method for each model separately with a different path.\"\n            )\n        engine = engines[0]","sourceCodeStart":418,"sourceCodeEnd":454,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/strategies/deepspeed.py#L418-L454","documentation":"DeepSpeed's engine serializes the entire training state itself, so a custom filter callback for selecting/filtering what gets saved cannot be applied. Passing filter=... to DeepSpeedStrategy.save_checkpoint raises TypeError.","triggerScenarios":"fabric.save_checkpoint(path, state, filter=fn) with strategy='deepspeed', where filter is a callable transforming the state dict in other strategies.","commonSituations":"Checkpoint-filtering helpers (e.g. saving only the model, stripping EMA/optimizer state) reused across strategies; FSDP/DDP code migrated to DeepSpeed.","solutions":["Remove the filter argument under DeepSpeed and rely on what the engine saves","If you need a reduced checkpoint, save the raw deepspeed checkpoint and post-process it, or select state contents before calling save_checkpoint","Gate filter usage on strategy type in your save helper"],"exampleFix":"# before\nfabric.save_checkpoint(path, state, filter=lambda k, v: k == \"model\")\n# after (deepspeed)\nfabric.save_checkpoint(path, state)","handlingStrategy":"validation","validationCode":"from lightning.fabric.strategies.deepspeed import DeepSpeedStrategy\nif isinstance(fabric.strategy, DeepSpeedStrategy):\n    fabric.save_checkpoint(path, state)  # no filter\nelse:\n    fabric.save_checkpoint(path, state, filter=filter_fn)","typeGuard":"from lightning.fabric.strategies.deepspeed import DeepSpeedStrategy\n\ndef supports_checkpoint_filter(strategy) -> bool:\n    return not isinstance(strategy, DeepSpeedStrategy)","tryCatchPattern":"try:\n    fabric.save_checkpoint(path, state, filter=fn)\nexcept TypeError:\n    fabric.save_checkpoint(path, state)","preventionTips":["Apply filtering before building state instead of via the filter kwarg under deepspeed"],"tags":["deepspeed","checkpointing","unsupported-argument","pytorch-lightning"],"backgroundTag":"unsupported-argument","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}