{"record":{"id":"6397f1fb35d3ae6d","repo":"jax-ml/jax","slug":"iterations-must-be-positive","errorCode":null,"errorMessage":"{iterations=} must be positive","messagePattern":"(.+?) must be positive","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/experimental/mosaic/gpu/profiler.py","lineNumber":166,"sourceCode":"      ``mode=\"cupti\"``. When greater than 1, the return type will become a list\n      of measurements.\n\n  Returns:\n    A function that accepts the same inputs as ``f`` and returns\n    ``(f_outputs, timings)``, where ``f_outputs`` are the outputs of ``f``,\n    and ``timings`` is either a float or a list of tuples, depending on\n    ``aggregate``. If no kernels are launched, ``timings`` is ``None``.\n\n  Notes:\n    `CUPTI (CUDA Profiling Tools Interface)\n    <https://docs.nvidia.com/cupti/index.html>`_ is a high-accuracy profiling\n    API used by Nsight Systems and Nsight Compute. The CUPTI API only allows a\n    single subscriber, so ``measure`` cannot be used with other CUPTI-based\n    tools like CUDA-GDB, Compute Sanitizer, Nsight Systems, or Nsight\n    Compute.\n  \"\"\"  # fmt: skip\n  if iterations < 1:\n    raise ValueError(f\"{iterations=} must be positive\")\n  return Cupti().measure(f, aggregate=aggregate, iterations=iterations)\n\n\nclass ProfilerSpec:\n  ENTER = 0\n  EXIT = 1 << 31\n\n  def __init__(\n      self,\n      entries_per_warpgroup: int,\n      dump_path: str = \"sponge\",\n      trace_scope: ThreadSubset = ThreadSubset.WARPGROUP,\n      bounds_check: bool = False,\n  ):\n    \"\"\"Profiler configuration.\n\n    Args:\n      entries_per_warpgroup: The size of the profile buffer. Each begin/end","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/experimental/mosaic/gpu/profiler.py#L148-L184","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass a positive integer (>= 1) for iterations","If iterations is computed, guard with max(1, n) or validate before calling measure"],"exampleFix":"// before\nres = measure(f, iterations=n // world_size)  # may be 0\n\n// after\nres = measure(f, iterations=max(1, n // world_size))","handlingStrategy":"validation","validationCode":"if iterations < 1:\n    raise ValueError('iterations must be >= 1')\nresult = measure(f, iterations=iterations)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp computed iteration counts with max(1, n)","Treat iterations as a required positive int in your API wrappers"],"tags":["profiling","mosaic","gpu","argument-validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}