{"record":{"id":"6d72197133444ff1","repo":"jax-ml/jax","slug":"process-id-and-num-processes-must-be-nonnegative","errorCode":null,"errorMessage":"process_id and num_processes must be nonnegative, with process_id < num_processes. Got process_id={process_id}, num_processes={num_processes}.","messagePattern":"process_id and num_processes must be nonnegative, with process_id < num_processes\\. Got process_id=(.+?), num_processes=(.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/distributed.py","lineNumber":149,"sourceCode":"              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\n                                os.environ.get('JAX_COORDINATOR_BIND_ADDRESS',\n                                               default_coordinator_bind_address))\n    if coordinator_bind_address is None:\n      raise ValueError('coordinator_bind_address should be defined.')\n\n    if local_device_ids:\n      visible_devices = ','.join(str(x) for x in local_device_ids)\n      logger.info('JAX distributed initialized with visible devices: %s', visible_devices)\n      config.update(\"jax_cuda_visible_devices\", visible_devices)\n      config.update(\"jax_rocm_visible_devices\", visible_devices)","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/distributed.py#L131-L167","documentation":"Beyond type checks, initialize validates the range 0 <= process_id < num_processes. A rank outside the world size (negative, or >= num_processes) raises this ValueError reporting both values.","triggerScenarios":"process_id=8 with num_processes=8; negative ranks; inconsistent rank/world-size env vars, e.g. RANK from a different launcher than WORLD_SIZE.","commonSituations":"Mixing launcher env vars (torchrun RANK with a hardcoded world size); off-by-one in manual rank assignment; env leakage between sequential jobs in CI.","solutions":["Ensure rank and world size come from the same launcher source: int(os.environ['RANK']) and int(os.environ['WORLD_SIZE'])","Add a launch-time assertion: assert 0 <= rank < world_size","Unset stale job env vars between runs (env -i or fresh shells)"],"exampleFix":"# before\nrank, world = int(os.environ['RANK']), 8  # hardcoded, RANK may be 8\n# after\nrank = int(os.environ['RANK']); world = int(os.environ['WORLD_SIZE'])\nassert 0 <= rank < world\njax.distributed.initialize(coordinator_address=addr,\n    num_processes=world, process_id=rank)","handlingStrategy":"validation","validationCode":"rank, world = int(os.environ['RANK']), int(os.environ['WORLD_SIZE'])\nassert 0 <= rank < world","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Source rank and world size from one launcher","Clear leaked job env vars between CI runs"],"tags":["jax","distributed","rank-validation"],"backgroundTag":"config-value-out-of-range","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}