jax-ml/jax · error · TypeError

num_processes must be a positive int. Got num_processes={num

Error message

num_processes must be a positive int. Got num_processes={num_processes} of type {type(num_processes)}.

What it means

num_processes must be a Python int (positive); strings, floats, or other types fail the isinstance check and raise this TypeError showing the received value and its type.

Source

Thrown at jax/_src/distributed.py:146

              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.')

    if local_device_ids:
      visible_devices = ','.join(str(x) for x in local_device_ids)

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Convert: num_processes=int(os.environ['WORLD_SIZE'])
2. Use argparse with type=int for CLI flags
3. Assert isinstance(num_processes, int) and num_processes > 0 in launch scripts

Example fix

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

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

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

When it happens

Trigger: jax.distributed.initialize(num_processes='8'), num_processes=8.0, or a value parsed from a config string without conversion.

Common situations: Env var read without int(); CLI argparse without type=int; YAML configs yielding strings; computed world sizes as floats.

Related errors

• Number of processes must be defined.
• process_id must be a nonnegative int. Got process_id={proces
• shard_map requires a `jax.sharding.Mesh` or a `jax.sharding.
• Mapped away dimension of inputs passed to vmap should be sha
• {name} was requested to map a value of non-array type {core.

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