{"record":{"id":"55552f3f43fd1881","repo":"Lightning-AI/pytorch-lightning","slug":"the-hybrid-sharding-strategy-requires-you-to-pass","errorCode":null,"errorMessage":"The hybrid sharding strategy requires you to pass at least one of the parameters: `auto_wrap_policy`, `process_group` tuple, or `device_mesh`.","messagePattern":"The hybrid sharding strategy requires you to pass at least one of the parameters: `auto_wrap_policy`, `process_group` tuple, or `device_mesh`\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/strategies/fsdp.py","lineNumber":870,"sourceCode":"\n\ndef _init_sharding_strategy(sharding_strategy: \"_SHARDING_STRATEGY\", kwargs: dict) -> \"ShardingStrategy\":\n    from torch.distributed.fsdp import ShardingStrategy\n\n    if kwargs.get(\"process_group\") is not None and kwargs.get(\"device_mesh\") is not None:\n        raise ValueError(\n            \"The arguments `FSDPStrategy(process_group=..., device_mesh=...)` are mutually exclusive.\"\n            \"Pass only one of them.\"\n        )\n\n    strategy = ShardingStrategy[sharding_strategy.upper()] if isinstance(sharding_strategy, str) else sharding_strategy\n    if (\n        \"HYBRID\" in strategy.name\n        and kwargs.get(\"auto_wrap_policy\") is None\n        and kwargs.get(\"process_group\") is None\n        and kwargs.get(\"device_mesh\") is None\n    ):\n        raise RuntimeError(\n            \"The hybrid sharding strategy requires you to pass at least one of the parameters: `auto_wrap_policy`,\"\n            \" `process_group` tuple, or `device_mesh`.\"\n        )\n    return strategy\n\n\ndef _optimizer_has_flat_params(optimizer: Optimizer) -> bool:\n    return any(\n        getattr(param, \"_fsdp_flattened\", False) for group in optimizer.param_groups for param in group[\"params\"]\n    )\n\n\ndef _get_sharded_state_dict_context(module: Module) -> Generator[None, None, None]:\n    from torch.distributed.fsdp import FullyShardedDataParallel as FSDP\n    from torch.distributed.fsdp.api import ShardedOptimStateDictConfig, ShardedStateDictConfig, StateDictType\n\n    state_dict_config = ShardedStateDictConfig(offload_to_cpu=True)\n    optim_state_dict_config = ShardedOptimStateDictConfig(offload_to_cpu=True)","sourceCodeStart":852,"sourceCodeEnd":888,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/strategies/fsdp.py#L852-L888","documentation":"This error is raised by Lightning Fabric's FSDP strategy when the user selects a hybrid sharding variant ('HYBRID_SHARD' or '_HYBRID_SHARD_ZERO2') but does not supply any of the three parameters that define the intra-node group boundaries: auto_wrap_policy, a process_group tuple, or a device_mesh. Hybrid sharding needs to know which ranks form the inner shard group versus the outer replicated group; without one of these, the sharding topology is undefined and Lightning refuses to construct the strategy.","triggerScenarios":"Calling Fabric(strategy='fsdp_hybrid_shard') or FSDPStrategy(sharding_strategy='HYBRID_SHARD') (or the _HYBRID_SHARD_ZERO2 variants) without passing auto_wrap_policy, process_group=(...), or device_mesh=... to FSDPStrategy/__init__.","commonSituations":"Switching an existing FSDP config string from 'fsdp' to 'fsdp_hybrid_shard' assuming it works out of the box; upgrading examples that only set sharding_strategy; copying a plain FSDP setup into a multi-node job where hybrid sharding was recommended.","solutions":["Pass an auto_wrap_policy, e.g. size_based_auto_wrap_policy from torch.distributed.fsdp.wrap, to FSDPStrategy","Or pass a process_group tuple: process_group=(intra_node_group, inter_node_group) created with torch.distributed.new_group","Or pass a torch.distributed.device_mesh.DeviceMesh initialized over your world","If you don't need intra-node sharding with inter-node replication, use the plain 'fsdp' strategy instead"],"exampleFix":"# before\nstrategy = FSDPStrategy(sharding_strategy=\"HYBRID_SHARD\")\n\n# after\nfrom torch.distributed.fsdp.wrap import size_based_auto_wrap_policy\nstrategy = FSDPStrategy(\n    sharding_strategy=\"HYBRID_SHARD\",\n    auto_wrap_policy=size_based_auto_wrap_policy,\n)","handlingStrategy":"validation","validationCode":"kwargs = {\"auto_wrap_policy\": None, \"process_group\": None, \"device_mesh\": None}\n# or your actual FSDPStrategy kwargs\nif \"HYBRID\" in str(sharding_strategy).upper() or \"hybrid\" in str(strategy_name):\n    if all(v is None for v in (kwargs.get(\"auto_wrap_policy\"), kwargs.get(\"process_group\"), kwargs.get(\"device_mesh\"))):\n        raise ValueError(\"HYBRID sharding needs auto_wrap_policy, process_group, or device_mesh\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default to plain 'fsdp' unless you specifically need intra-node sharding + inter-node replication","When choosing a hybrid strategy, always pair it with an auto_wrap_policy or explicit mesh/groups in the same config"],"tags":["pytorch-lightning","fabric","fsdp","distributed","sharding"],"backgroundTag":"distributed-strategy-misconfiguration","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}