jax-ml/jax · error · ValueError

coordinator_address should be defined.

Error message

coordinator_address should be defined.

What it means

jax.distributed.initialize requires a coordinator address (host:port of process 0) unless cluster auto-detection supplied one. Passing None (the default when no detection method is used) raises this ValueError immediately.

Source

Thrown at jax/_src/distributed.py:137

    if local_device_ids is None and (env_ids := os.environ.get('JAX_LOCAL_DEVICE_IDS')):
      local_device_ids = list(map(int, env_ids.split(",")))

    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.

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Pass coordinator_address='10.0.0.1:12345' (process 0's IP and a free port) on every process
2. Or use a cluster_detection_method (e.g. slurm) so the address is auto-derived
3. Export JAX_COORDINATOR_ADDRESS and read it in code: os.environ['JAX_COORDINATOR_ADDRESS']

Example fix

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

import os
addr = os.environ.get('JAX_COORDINATOR_ADDRESS')
assert addr, 'JAX_COORDINATOR_ADDRESS must be set on all ranks'

try:
    jax.distributed.initialize(coordinator_address=addr, ...)
except ValueError as e:
    if 'coordinator_address' in str(e):
        addr = os.environ['JAX_COORDINATOR_ADDRESS']; retry

When it happens

Trigger: jax.distributed.initialize() with no coordinator_address and no cluster_detection_method; or explicitly passing coordinator_address=None on worker processes.

Common situations: Launching multi-host jobs with a launcher (torchrun/mpirun/slurm) but forgetting to plumb the coordinator env var into initialize; copy-pasted initialization code missing the address argument.

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

• Number of processes must be defined.
• The process id of the current process must be defined.
• Mapped away dimension of inputs passed to vmap should be sha
• invalid truth value {val!r} for environment {varname!r}
• Unrecognized config option: {name}

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