{"record":{"id":"efddeefc2771f1fa","repo":"jax-ml/jax","slug":"number-of-processes-must-be-defined","errorCode":null,"errorMessage":"Number of processes must be defined.","messagePattern":"Number of processes must be defined\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/distributed.py","lineNumber":139,"sourceCode":"      local_device_ids = list(map(int, env_ids.split(\",\")))\n\n    if (cluster_detection_method != 'deactivate' and\n        None in (coordinator_address, num_processes, process_id, local_device_ids)):\n      (coordinator_address, num_processes, process_id, local_device_ids) = (\n          clusters.ClusterEnv.auto_detect_unset_distributed_params(\n              coordinator_address,\n              num_processes,\n              process_id,\n              local_device_ids,\n              cluster_detection_method,\n              initialization_timeout,\n          )\n      )\n\n    if coordinator_address is None:\n      raise ValueError('coordinator_address should be defined.')\n    if num_processes is None:\n      raise ValueError('Number of processes must be defined.')\n    if process_id is None:\n      raise ValueError('The process id of the current process must be defined.')\n    if not isinstance(process_id, int):\n      raise TypeError(\"process_id must be a nonnegative int. \"\n                      f\"Got process_id={process_id} of type {type(process_id)}.\")\n    if not isinstance(num_processes, int):\n      raise TypeError(\"num_processes must be a positive int. \"\n                      f\"Got num_processes={num_processes} of type {type(num_processes)}.\")\n    if not (0 <= process_id < num_processes):\n      raise ValueError(\"process_id and num_processes must be nonnegative, with process_id < num_processes. \"\n                       f\"Got process_id={process_id}, num_processes={num_processes}.\")\n\n    self.coordinator_address = coordinator_address\n\n    # The default value of [::]:port tells the coordinator to bind to all\n    # available addresses on the same port as coordinator_address.\n    default_coordinator_bind_address = '[::]:' + coordinator_address.rsplit(':', 1)[1]\n    coordinator_bind_address = (coordinator_bind_address or","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/distributed.py#L121-L157","documentation":"jax.distributed.initialize requires num_processes (total world size) to be explicitly set; it has no default. Omitting it raises this ValueError before any connection is attempted.","triggerScenarios":"jax.distributed.initialize(coordinator_address=...) without num_processes; passing num_processes=None explicitly.","commonSituations":"Single-script multi-GPU launches where the user assumed JAX infers world size; missing plumbing from torchrun/mpirun env vars (NRANKS/WORLD_SIZE).","solutions":["Pass num_processes equal to the launcher's world size, e.g. int(os.environ['NRANKS']) or WORLD_SIZE","Use a cluster_detection_method that infers process counts (slurm/torchrun)","Double-check that every process passes the same num_processes value"],"exampleFix":"# before\njax.distributed.initialize(coordinator_address=addr)\n# after\njax.distributed.initialize(coordinator_address=addr,\n    num_processes=int(os.environ['WORLD_SIZE']),\n    process_id=int(os.environ['RANK']))","handlingStrategy":"validation","validationCode":"import os\nnp_ = int(os.environ.get('WORLD_SIZE', os.environ.get('NRANKS', 0)))\nassert np_ > 0, 'num_processes unresolved'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive world size from the launcher, never hardcode partially","Assert all three (address, num_processes, process_id) before initialize"],"tags":["jax","distributed","world-size","config"],"backgroundTag":"missing-required-config","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}