What causes "could not understand directive {directive!r}" in jax-ml/jax?

Use only comma-separated integers in the directive, e.g. jnp.r_['0,2,-1', a, b]

jax-ml/jax · error · ValueError

could not understand directive {directive!r}

Error message

could not understand directive {directive!r}

What it means

Raised by jax.numpy.r_ / jnp.r_ (and c_) when the bracket directive string cannot be parsed. Directives like '0,2' set (axis, ndmin) or '2,3,1' sets (axis, ndmin, trans1d); the comma-separated parts must all be integers. If int() conversion of any part fails, this ValueError is raised.

Source

Thrown at jax/_src/numpy/index_tricks.py:175

    if isinstance(directive, str):
      key_tup = key_tup[1:]
      # check two special cases: matrix directives
      if directive == "r":
        params[-1] = 0
      elif directive == "c":
        params[-1] = 1
      else:
        vec: list[Any] = directive.split(",")
        k = len(vec)
        if k < 4:
          vec += params[k:]
        else:
          # ignore everything after the first three comma-separated ints
          vec = vec[:3] + [params[-1]]
        try:
          params = list(map(int, vec))
        except ValueError as err:
          raise ValueError(
            f"could not understand directive {directive!r}"
          ) from err

    axis, ndmin, trans1d, matrix = params

    output = []
    for item in key_tup:
      if isinstance(item, slice):
        newobj = _make_1d_grid_from_slice(item, op_name=self.op_name)
        item_ndim = 0
      elif isinstance(item, str):
        raise ValueError("string directive must be placed at the beginning")
      else:
        newobj = array(item, copy=False)
        item_ndim = newobj.ndim

      newobj = array(newobj, copy=False, ndmin=ndmin)

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

Use only comma-separated integers in the directive, e.g. jnp.r_['0,2,-1', a, b]
Use the 'r'/'c' shorthand strings for simple row/column stacking
For complex layout needs, call jnp.stack/jnp.concatenate/jnp.expand_dims explicitly

Example fix

# before
out = jnp.r_['0,2,outer', a, b]
# after
out = jnp.r_['0,2', a, b]  # integers only

Defensive patterns

Strategy: validation

Validate before calling

def valid_directive(d: str) -> bool:
    if d in ('r', 'c'):
        return True
    parts = d.split(',')
    return all(p.strip().lstrip('-').isdigit() for p in parts)

Try / catch

try:
    out = jnp.r_['0,2', a, b]
except ValueError as e:
    if 'could not understand directive' in str(e):
        out = jnp.concatenate([jnp.expand_dims(x, 0) for x in (a, b)], axis=0)
    else:
        raise

Prevention

Keep directives to 1-3 comma-separated integers
Prefer explicit jnp.concatenate/stack for anything beyond simple stacking
Test directive strings in a helper that validates before use

When it happens

Trigger: jnp.r_['0,2,axis'] or jnp.r_['1.5,2', ...] — non-integer tokens in the directive; also typos like '0;2'. Only 'r' and 'c' are special-cased.

Common situations: Copy-pasting numpy r_ examples with wrong directive syntax; forgetting the quote style; expecting slice syntax like '-1:1:5j' inside the directive string instead of as the indexed item.

Related errors

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