jax-ml/jax · error · ValueError

Vector clock size must be at least 1, but got {self.vector_c

Error message

Vector clock size must be at least 1, but got {self.vector_clock_size}.

What it means

The interpret-mode params dataclass validates vector_clock_size (used for race detection across simulated cores) must be at least 1 when provided; passing 0 or negative raises this ValueError in __post_init__.

Source

Thrown at jax/_src/pallas/mosaic/interpret/params.py:100

  """

  detect_races: bool = False
  out_of_bounds_reads: Literal["raise", "uninitialized"] = "raise"
  skip_floating_point_ops: bool = False
  uninitialized_memory: Literal["nan", "zero"] = "nan"
  num_cores_or_threads: int = 1
  vector_clock_size: int | None = None
  logging_mode: LoggingMode | None = None

  def __post_init__(self):
    if self.num_cores_or_threads < 1:
      raise ValueError(
          "Number of cores or threads must be at least 1, but got"
          f" {self.num_cores_or_threads}."
      )
    if self.vector_clock_size is not None and self.vector_clock_size < 1:
      # Further validation is done in `get_vector_clock_size` below.
      raise ValueError(
          "Vector clock size must be at least 1, but got"
          f" {self.vector_clock_size}."
      )

  def get_vector_clock_size(self, num_devices) -> int:
    """Returns the number of vector clocks to use for TPU interpret mode.`"""
    num_cores_or_threads = num_devices * self.num_cores_or_threads
    if self.vector_clock_size is not None:
      if num_cores_or_threads >= self.vector_clock_size:
        raise ValueError(
            f"Vector clock size ({self.vector_clock_size}) must be greater than"
            f" the total number of cores/threads ({num_cores_or_threads})."
        )
      return self.vector_clock_size
    else:
      # Default to twice the total number of cores/threads.
      return 2 * num_cores_or_threads

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

Pass a positive integer or leave vector_clock_size=None to use the default from get_vector_clock_size
Clamp computed values: max(1, computed_clocks)
Validate config before constructing the params object

Example fix

# before
params = interpret_params(vector_clock_size=num_devices - 1)  # 0 with 1 device
# after
params = interpret_params(vector_clock_size=max(1, num_devices - 1))  # or omit

Defensive patterns

Strategy: validation

Validate before calling

assert vector_clock_size is None or (isinstance(vector_clock_size, int) and vector_clock_size >= 1)

Type guard

def is_valid_clock_size(n) -> bool:
    return n is None or (isinstance(n, int) and not isinstance(n, bool) and n >= 1)

Try / catch

try:
    params = InterpretParams(vector_clock_size=n)
except ValueError as e:
    if 'Vector clock size' in str(e):
        params = InterpretParams()  # use default via get_vector_clock_size

Prevention

Omit vector_clock_size unless race detection needs a specific size
Clamp computed values with max(1, x)
Treat 0 from computed expressions as None/default

When it happens

Trigger: Constructing interpret params with vector_clock_size=0 or negative — commonly from a computed value (e.g., number of clocks derived from device count or grid size) that evaluates to 0.

Common situations: Enabling race detection with a clock size derived from an empty device list or zero-sized grid; config plumbing where None vs 0 is confused; automated tuning scripts producing 0.

Related errors

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