jax-ml/jax · error · ValueError

Num arrivals must be at least 1, but got {n}

Error message

Num arrivals must be at least 1, but got {n}

What it means

BarrierSpec.__post_init__ validates that num_arrivals >= 1. Arrivals count the threads/blocks that must arrive at an asynchronous barrier before it releases; zero or negative arrivals is nonsensical and rejected immediately at construction.

Source

Thrown at jax/_src/pallas/mosaic_gpu/core.py:1503

class Barrier:
  """Describes a barrier reference.

  Attributes:
    num_arrivals: The number of arrivals that will be recorded by this barrier.
    num_barriers: The number of barriers that will be created. Individual
      barriers can be accessed by indexing into the barrier Ref.
    orders_tensor_core: If False, a successful wait from one thread does not
      guarantee that the TensorCore-related operations in other threads have
      completed. Similarly, when False any TensorCore operation in the waiting
      thread is allowed to begin before the wait succeeds.
  """
  num_arrivals: int = 1
  num_barriers: int | Sequence[int] = 1
  orders_tensor_core: bool = False

  def __post_init__(self):
    if (n := self.num_arrivals) < 1:
      raise ValueError(f"Num arrivals must be at least 1, but got {n}")

    if isinstance(self.num_barriers, int):
      object.__setattr__(self, "num_barriers", (self.num_barriers,))
    else:
      object.__setattr__(self, "num_barriers", tuple(self.num_barriers))

  def get_array_aval(self) -> jax_core.ShapedArray:
    raise ValueError("Barriers are not arrays")

  def get_ref_aval(self) -> state.AbstractRef:
    ty = BarrierType(self.num_arrivals, self.orders_tensor_core)
    return state.AbstractRef(jax_core.ShapedArray(self.num_barriers, ty), SMEM)


@dataclasses.dataclass(frozen=True, kw_only=True)
class ClusterBarrier:
  collective_axes: tuple[str | tuple[str, ...], ...]
  num_barriers: int | Sequence[int] = 1

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Check the formula producing num_arrivals and clamp/validate it to >= 1
2. Pass num_arrivals explicitly as the number of arriving warps/blocks
3. Add an assert num_arrivals >= 1 near the configuration code

Example fix

// before
spec = plgpu.BarrierSpec(num_arrivals=num_warps // 4)  # 0 if num_warps < 4
// after
assert num_warps >= 4
spec = plgpu.BarrierSpec(num_arrivals=num_warps // 4)

assert num_arrivals >= 1, f'num_arrivals must be >= 1, got {num_arrivals}'

When it happens

Trigger: Constructing a BarrierSpec with num_arrivals=0 or negative — often from a computed arrival count (e.g. num_threads // divisor) that evaluates to 0.

Common situations: Deriving num_arrivals from a layout parameter that can be 0 (empty warp config), arithmetic errors in warp-specialized pipeline setup, or defaults silently overwritten.

Related errors

• Sum of sizes {n} must be equal to dimension {axis} of the op
• Cannot pull iota along dimension {dimension} with None block
• Invalid memory space: {memory_space!r}
• Vector clock size ({self.vector_clock_size}) must be greater
• position {position} is out of range for clock {self.clock}

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