{"record":{"id":"18025949e1447046","repo":"jax-ml/jax","slug":"vector-clock-size-self-vector-clock-size-must","errorCode":null,"errorMessage":"Vector clock size ({self.vector_clock_size}) must be greater than the total number of cores/threads ({num_cores_or_threads}).","messagePattern":"Vector clock size \\((.+?)\\) must be greater than the total number of cores/threads \\((.+?)\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/pallas/mosaic/interpret/params.py","lineNumber":110,"sourceCode":"  def __post_init__(self):\n    if self.num_cores_or_threads < 1:\n      raise ValueError(\n          \"Number of cores or threads must be at least 1, but got\"\n          f\" {self.num_cores_or_threads}.\"\n      )\n    if self.vector_clock_size is not None and self.vector_clock_size < 1:\n      # Further validation is done in `get_vector_clock_size` below.\n      raise ValueError(\n          \"Vector clock size must be at least 1, but got\"\n          f\" {self.vector_clock_size}.\"\n      )\n\n  def get_vector_clock_size(self, num_devices) -> int:\n    \"\"\"Returns the number of vector clocks to use for TPU interpret mode.`\"\"\"\n    num_cores_or_threads = num_devices * self.num_cores_or_threads\n    if self.vector_clock_size is not None:\n      if num_cores_or_threads >= self.vector_clock_size:\n        raise ValueError(\n            f\"Vector clock size ({self.vector_clock_size}) must be greater than\"\n            f\" the total number of cores/threads ({num_cores_or_threads}).\"\n        )\n      return self.vector_clock_size\n    else:\n      # Default to twice the total number of cores/threads.\n      return 2 * num_cores_or_threads\n\n\n@dataclasses.dataclass(frozen=True, kw_only=True)\nclass InterpretParams(SharedInterpretParams):\n  \"\"\"Parameters for TPU interpret mode.\n\n  TPU interpret mode is a way run Pallas TPU kernels on CPU, while simulating\n  a TPU's shared memory (HBM, VMEM, etc.), communication (remote and local\n  DMAs), and synchronization operations (semaphores, barriers, etc.).  This mode\n  is intended for debugging and testing.\n","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/pallas/mosaic/interpret/params.py#L92-L128","documentation":"Raised by Mosaic TPU interpret-mode parameter handling when an explicitly configured vector_clock_size is not strictly greater than the total number of simulated cores/threads (num_devices * num_cores_or_threads). The interpret mode simulates parallel execution with vector clocks for race detection; there must be more clock slots than simulated threads.","triggerScenarios":"Calling interpret-mode Pallas/Mosaic kernels with InterpretParams(vector_clock_size=N) where N <= num_devices * num_cores_or_threads, e.g. running multi-device simulation with a small explicit clock size.","commonSituations":"Copying interpret params configured for 1 device/1 core and then simulating multiple devices; explicitly setting vector_clock_size while also raising num_cores_or_threads; version changes that altered the multiplication semantics.","solutions":["Omit vector_clock_size (set it to None) so interpret mode defaults to 2x the total cores/threads","Set vector_clock_size to a value strictly greater than num_devices * num_cores_or_threads (e.g. 2x + 1)","Reduce num_cores_or_threads or the simulated num_devices"],"exampleFix":"// before\nparams = mosaic_interpret.InterpretParams(num_cores_or_threads=4, vector_clock_size=4)\n// after\nparams = mosaic_interpret.InterpretParams(num_cores_or_threads=4, vector_clock_size=None)  # auto: 2x total","handlingStrategy":"validation","validationCode":"total = num_devices * params.num_cores_or_threads\nassert params.vector_clock_size is None or params.vector_clock_size > total, 'vector_clock_size must exceed total cores/threads'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer leaving vector_clock_size unset (None) to use the automatic default","Compute total = num_devices * num_cores_or_threads whenever manually configuring clock size"],"tags":["jax","pallas","mosaic","tpu","interpret-mode","vector-clock","config"],"backgroundTag":"invalid-configuration-value","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}