jax-ml/jax · error · ValueError

Unknown action: {action}

Error message

Unknown action: {action}

What it means

The helper _copy_start_or_wait dispatches on an action string that must be exactly 'start' or 'wait' for async copy descriptors. Any other string (typo, wrong case, new action like 'commit') raises ValueError.

Source

Thrown at jax/_src/pallas/mosaic/helpers.py:42

def sync_copy(src_ref, dst_ref, *, add: bool = False) -> None:
  """Synchronously copies a PyTree of refs to another PyTree of refs."""
  if not jax.tree.leaves(src_ref):
    # No buffers to copy so skip the function.
    return

  @functools.partial(
      pl_primitives.run_scoped, sem=tpu_core.SemaphoreType.DMA(())
  )
  def _(sem):
    def _copy_start_or_wait(action, src_ref, dst_ref):
      descriptor = plm_primitives.make_async_copy(src_ref, dst_ref, sem)
      if action == "start":
        descriptor.start(add=add)
      elif action == "wait":
        descriptor.wait()
      else:
        raise ValueError(f"Unknown action: {action}")

    jax.tree.map(
        functools.partial(_copy_start_or_wait, "start"),
        src_ref,
        dst_ref,
    )
    jax.tree.map(
        functools.partial(_copy_start_or_wait, "wait"),
        src_ref,
        dst_ref,
    )


def run_on_first_core(core_axis_name: str):
  """Runs a function on the first core in a given axis."""
  num_cores = jax.lax.axis_size(core_axis_name)
  if num_cores == 1:
    return lambda f: f()

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Use exactly 'start' or 'wait' as the action string
2. If you need a new action, implement it in the descriptor API rather than the dispatch string
3. Avoid relying on this private helper; use pltpu async_copy primitives instead

Example fix

// before
_copy_start_or_wait(src, dst, action='Start')  # wrong case
// after
_copy_start_or_wait(src, dst, action='start')

assert action in ('start', 'wait'), action

def is_copy_action(a: str) -> TypeGuard[Literal['start','wait']]: return a in ('start','wait')

When it happens

Trigger: Calling the async copy helper (used by Mosaic/TensorCore copy plumbing) with an action argument other than 'start'/'wait' — typically only reachable from internal code or monkey-patched wrappers passing a custom action.

Common situations: Extending JAX internals with new async-copy actions; typos in patched versions; calling private helpers directly from user code.

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

• Loads are only allowed on VMEM and SMEM references.
• Loads and stores are only allowed on VMEM and SMEM reference
• Compiler params for platform {platform} cannot be used for {
• Memory space {self.memory_space} is not supported by mesh {s
• Acc ref must be at least 2D, got shape {shape}

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