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 process_id (this process's rank) to be set explicitly; there is no default. None raises this ValueError during argument validation.

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)

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={proces
• shard_map out_specs rank error (msg from _spec_rank_error)
• Mapped away dimension of inputs passed to vmap should be sha

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