jax-ml/jax · error · ValueError

The process id of the current process must be defined.

Error message

The process id of the current process must be defined.

What it means

jax.distributed.initialize requires the rank of the current process; after optional cluster auto-detection, process_id was still None, so the multi-process configuration is incomplete and initialization cannot proceed.

Solutions

1. Pass process_id from the launcher: int(os.environ['RANK']) (torchrun) or the SLURM procid
2. Use cluster_detection_method to infer rank automatically
3. Verify process_id is the global rank, not the local node rank (LOCAL_RANK)

Example fix

# before
jax.distributed.initialize(coordinator_address=addr, num_processes=8)
# after
jax.distributed.initialize(coordinator_address=addr, num_processes=8,
    process_id=int(os.environ['RANK']))

import os
rank = os.environ.get('RANK') or os.environ.get('SLURM_PROCID')
assert rank is not None, 'process_id unresolved'

When it happens

Trigger: Calling initialize without process_id, or with process_id=None, even when coordinator_address and num_processes are provided.

Common situations: Rank plumbing from torchrun/mpirun/slurm forgotten; assuming rank 0 implicitly; env var name mismatch (RANK vs LOCAL_RANK).

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• coordinator_address should be defined.
• Number of processes must be defined.
• process_id must be a nonnegative int. Got process_id=
• shard_map out_specs rank error (msg from _spec_rank_error)
• Attempting to set log level

AI-assisted analysis of jax-ml/jax@1e1c6a8fc0 (2026-08-27). Data as JSON: /api/errors/9d4d697d6ff45a1c. Report an issue: GitHub.

Appendix: source

Thrown at jax/_src/distributed.py:141

    if (cluster_detection_method != 'deactivate' and
        None in (coordinator_address, num_processes, process_id, local_device_ids)):
      (coordinator_address, num_processes, process_id, local_device_ids) = (
          clusters.ClusterEnv.auto_detect_unset_distributed_params(
              coordinator_address,
              num_processes,
              process_id,
              local_device_ids,
              cluster_detection_method,
              initialization_timeout,
          )
      )

    if coordinator_address is None:
      raise ValueError('coordinator_address should be defined.')
    if num_processes is None:
      raise ValueError('Number of processes must be defined.')
    if process_id is None:
      raise ValueError('The process id of the current process must be defined.')
    if not isinstance(process_id, int):
      raise TypeError("process_id must be a nonnegative int. "
                      f"Got process_id={process_id} of type {type(process_id)}.")
    if not isinstance(num_processes, int):
      raise TypeError("num_processes must be a positive int. "
                      f"Got num_processes={num_processes} of type {type(num_processes)}.")
    if not (0 <= process_id < num_processes):
      raise ValueError("process_id and num_processes must be nonnegative, with process_id < num_processes. "
                       f"Got process_id={process_id}, num_processes={num_processes}.")

    self.coordinator_address = coordinator_address

    # The default value of [::]:port tells the coordinator to bind to all
    # available addresses on the same port as coordinator_address.
    default_coordinator_bind_address = '[::]:' + coordinator_address.rsplit(':', 1)[1]
    coordinator_bind_address = (coordinator_bind_address or
                                os.environ.get('JAX_COORDINATOR_BIND_ADDRESS',
                                               default_coordinator_bind_address))

View on GitHub (pinned to 1e1c6a8fc0)