jax-ml/jax · error · TypeError

process_id must be a nonnegative int. Got process_id={proces

Error message

process_id must be a nonnegative int. Got process_id={process_id} of type {type(process_id)}.

What it means

process_id must be a Python int >= 0; passing a string, float, None-alternative, or negative value raises this TypeError with the offending value and type included in the message.

Source

Thrown at jax/_src/distributed.py:143

      (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))
    if coordinator_bind_address is None:
      raise ValueError('coordinator_bind_address should be defined.')

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Wrap in int(): process_id=int(os.environ['RANK'])
2. Validate 0 <= process_id < num_processes before calling initialize
3. Sanitize config files that store rank/world size as strings

Example fix

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

process_id = int(os.environ['RANK'])
assert isinstance(process_id, int) and process_id >= 0

def valid_rank(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 0

When it happens

Trigger: jax.distributed.initialize(process_id='0') (string from env/parsing), process_id=-1, or a float like 0.0; any non-int type fails isinstance(process_id, int).

Common situations: Reading rank from environment without int() conversion; YAML/JSON config values parsed as strings; numpy ints usually pass but floats from computed ranks do not.

Related errors

• The process id of the current process must be defined.
• num_processes must be a positive int. Got num_processes={num
• shard_map out_specs rank error (msg from _spec_rank_error)
• shard_map requires a `jax.sharding.Mesh` or a `jax.sharding.
• 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/65fb31390299c80b. Report an issue: GitHub.