{"record":{"id":"00c18f227c9f7d2c","repo":"Lightning-AI/pytorch-lightning","slug":"num-processes-should-be-1-got-num-processes","errorCode":null,"errorMessage":"`num_processes` should be >= 1, got {num_processes}.","messagePattern":"`num_processes` should be >= 1, got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/utilities/distributed.py","lineNumber":385,"sourceCode":"        super().__init__(_DatasetSamplerWrapper(sampler), *args, **kwargs)\n\n    @override\n    def __iter__(self) -> Iterator:\n        self.dataset.reset()\n        return (self.dataset[index] for index in super().__iter__())\n\n    @override\n    def set_epoch(self, epoch: int) -> None:\n        super().set_epoch(epoch)\n        # Forward set_epoch to the original sampler if it supports it\n        original_sampler = self.dataset._sampler\n        if hasattr(original_sampler, \"set_epoch\") and callable(original_sampler.set_epoch):\n            original_sampler.set_epoch(epoch)\n\n\ndef _suggested_max_num_threads(num_processes: int = 1) -> int:\n    if num_processes < 1:\n        raise ValueError(f\"`num_processes` should be >= 1, got {num_processes}.\")\n    return max(1, _num_cpus_available() // num_processes)\n\n\ndef _set_num_threads_if_needed(num_processes: int = 1) -> None:\n    if \"OMP_NUM_THREADS\" not in os.environ:\n        num_threads = _suggested_max_num_threads(num_processes)\n        torch.set_num_threads(num_threads)\n        os.environ[\"OMP_NUM_THREADS\"] = str(num_threads)\n\n\ndef _distributed_is_initialized() -> bool:\n    # `is_initialized` is only defined conditionally\n    # https://github.com/pytorch/pytorch/blob/v2.1.0/torch/distributed/__init__.py#L25\n    # this might happen to MacOS builds from source (default) or any build from source that sets `USE_DISTRIBUTED=0`\n    return torch.distributed.is_available() and torch.distributed.is_initialized()\n\n\nclass _InfiniteBarrier:","sourceCodeStart":367,"sourceCodeEnd":403,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/utilities/distributed.py#L367-L403","documentation":"Raised by Lightning's `_suggested_max_num_threads` when the number of processes used to derive a per-process CPU thread count is less than 1. The helper divides available CPUs by `num_processes` to suggest an `OMP_NUM_THREADS` value, so a non-positive process count is meaningless. It is typically reached via `_set_num_threads_if_needed` when Lightning or torchrun sets thread counts at launch.","triggerScenarios":"Calling `seed_everything`/Fabric or Trainer internals that invoke `_set_num_threads_if_needed(num_processes)` with 0 or a negative number; passing `num_processes=0` to a Fabric/launcher utility; computing num_processes as `world_size - 1` or from an env var that resolves to 0.","commonSituations":"Off-by-one when deriving device/process counts, passing a computed `num_processes` that is 0 on single-process runs, misconfigured launcher env vars (e.g. empty WORLD_SIZE coerced to 0).","solutions":["Ensure num_processes is at least 1 (e.g. `max(1, num_processes)`) before launching Fabric/Trainer or torchrun","Check how num_processes is derived: world_size, device count, or env vars must not yield 0","If calling the private helper directly, validate the argument first"],"exampleFix":"// before\nfabric = Fabric(num_processes=0)\n\n// after\nfrom lightning_fabric.utilities import _suggested_max_num_threads\nnum_processes = max(1, int(os.environ.get(\"WORLD_SIZE\", 1)))\nfabric = Fabric(num_processes=num_processes)","handlingStrategy":"validation","validationCode":"num_processes = max(1, int(num_processes))\nassert num_processes >= 1","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never derive num_processes from unchecked arithmetic (world_size - 1, len(devices) - 1)","Default to 1 when an env var is empty or unparseable"],"tags":["lightning","multiprocessing","configuration"],"backgroundTag":"invalid-argument-value","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}