jax-ml/jax · error · ValueError

Grid must be specified when using lookahead.

Error message

Grid must be specified when using lookahead.

What it means

When an input spec uses pipeline_mode with use_lookahead=True, the pipeline must know the kernel grid to compute fetch indices ahead of time. If grid is None (dynamic/deferred grid) at BufferSpec binding time, this ValueError is raised.

Source

Thrown at jax/_src/pallas/mosaic/pipeline.py:1489

    in_specs and out_specs.
  """
  # TODO(levskaya): generalize argument tree handling here and in emit_pipeline.
  num_in_specs = len(in_specs)
  in_specs = _normalize_specs(in_specs)
  out_specs = _normalize_specs(out_specs)
  in_specs, in_refs = _filter_specs_and_refs(in_specs, refs[:num_in_specs])
  out_specs, out_refs = _filter_specs_and_refs(out_specs, refs[num_in_specs:])
  def make_input_bref(in_spec, in_ref):
    in_aval = _ref_to_value_aval(in_ref)
    buffer_count = 2
    use_lookahead = False
    prefetched_count = 0
    if has_buffering := in_spec.pipeline_mode is not None:
      buffer_count = in_spec.pipeline_mode.buffer_count
      use_lookahead = in_spec.pipeline_mode.use_lookahead
      prefetched_count = in_spec.pipeline_mode.prefetched_count
    if use_lookahead and grid is None:
      raise ValueError("Grid must be specified when using lookahead.")
    is_trivial = _spec_has_trivial_windowing(in_spec, grid, in_aval.shape)
    if not has_buffering and is_trivial:
      buffer_count = 1

    sms = (in_ref.memory_space if isinstance(in_ref, state.TransformedRef) else
           core.typeof(in_ref).memory_space)
    return BufferedRef.input(
        in_spec,
        in_aval,
        buffer_count,
        grid_rank=len(grid),
        use_lookahead=use_lookahead,
        source_memory_space=sms,
        tiling=tiling,
        is_trivial_windowing=is_trivial,
        prefetched_count=prefetched_count,
    )
  in_brefs = jax.tree.map(make_input_bref, in_specs, in_refs)

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Pass an explicit tuple of Python ints / JAX arrays as grid when using lookahead
2. Or disable lookahead in the pipeline_mode of that input spec
3. Verify grid is passed at the same call site that receives in_specs with pipeline_mode

Example fix

# before
emit_pipeline(..., grid=None)  # with use_lookahead=True
# after
emit_pipeline(..., grid=(num_steps,))

assert grid is not None or not any(
    getattr(s, 'pipeline_mode', None) and s.pipeline_mode.use_lookahead for s in in_specs), \
    'lookahead requires an explicit grid'

When it happens

Trigger: Setting PipelineMode(use_lookahead=True) in an in_spec while calling the pipeline entry point without a concrete grid (grid=None), e.g. relying on a later grid specification.

Common situations: Adapting a kernel that previously ran without lookahead and without an explicit grid; using dynamic grid specification features while enabling lookahead.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Output buffering does not support lookahead.
• Axis {axis} is out of bounds for grid {self.grid}
• Revisited block {output_ranges[i]} of output {i} in iteratio
• Dimensions with parallel semantics must form a prefix of the
• program id was requested but no grid was provided.

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