jax-ml/jax · error · ValueError

{iterations=} must be positive

Error message

{iterations=} must be positive

What it means

Raised by mosaic.gpu.profiler.measure when the `iterations` argument is less than 1. The profiler needs at least one iteration to run the callable `f` under the CUPTI profiling API; zero or negative iteration counts are meaningless and are rejected up front.

Source

Thrown at jax/experimental/mosaic/gpu/profiler.py:166

      ``mode="cupti"``. When greater than 1, the return type will become a list
      of measurements.

  Returns:
    A function that accepts the same inputs as ``f`` and returns
    ``(f_outputs, timings)``, where ``f_outputs`` are the outputs of ``f``,
    and ``timings`` is either a float or a list of tuples, depending on
    ``aggregate``. If no kernels are launched, ``timings`` is ``None``.

  Notes:
    `CUPTI (CUDA Profiling Tools Interface)
    <https://docs.nvidia.com/cupti/index.html>`_ is a high-accuracy profiling
    API used by Nsight Systems and Nsight Compute. The CUPTI API only allows a
    single subscriber, so ``measure`` cannot be used with other CUPTI-based
    tools like CUDA-GDB, Compute Sanitizer, Nsight Systems, or Nsight
    Compute.
  """  # fmt: skip
  if iterations < 1:
    raise ValueError(f"{iterations=} must be positive")
  return Cupti().measure(f, aggregate=aggregate, iterations=iterations)


class ProfilerSpec:
  ENTER = 0
  EXIT = 1 << 31

  def __init__(
      self,
      entries_per_warpgroup: int,
      dump_path: str = "sponge",
      trace_scope: ThreadSubset = ThreadSubset.WARPGROUP,
      bounds_check: bool = False,
  ):
    """Profiler configuration.

    Args:
      entries_per_warpgroup: The size of the profile buffer. Each begin/end

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Pass a positive integer (>= 1) for iterations
2. If iterations is computed, guard with max(1, n) or validate before calling measure

Example fix

// before
res = measure(f, iterations=n // world_size)  # may be 0

// after
res = measure(f, iterations=max(1, n // world_size))

if iterations < 1:
    raise ValueError('iterations must be >= 1')
result = measure(f, iterations=iterations)

When it happens

Trigger: Calling measure(f, iterations=0) or passing a negative/computed-to-zero iterations value (e.g. derived from a benchmark-size calculation that produced 0).

Common situations: Programmatic warmup loops where iterations is computed from user input or benchmark parameters and can evaluate to 0; copy-paste from examples where iterations was optional.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unsupported trace scope: {trace_scope}
• Scope {spec.trace_scope} not supported
• Expected both or neither of scales to be specified.
• Scope {self.trace_scope} not supported
• Block size is not a multiple of {scope_size}

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