{"record":{"id":"37b2ef5503c3215f","repo":"jax-ml/jax","slug":"full-name-must-form-a-tree-prefix-of-the-corresp-37b2ef","errorCode":null,"errorMessage":"{full_name} must form a tree prefix of the corresponding values (up to pytree node types, so containers need only match in their number of children), but {where} has {len(prefix)} children while the corresponding container has {len(td_children)}","messagePattern":"(.+?) must form a tree prefix of the corresponding values \\(up to pytree node types, so containers need only match in their number of children\\), but (.+?) has (.+?) children while the corresponding container has (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/api.py","lineNumber":1907,"sourceCode":"  if isinstance(prefix, bool):\n    ret.extend([prefix] * td.num_leaves)\n    return\n  where = name + ''.join(f'[{i}]' for i in path)\n  if not isinstance(prefix, tuple):\n    raise ValueError(\n        f\"{full_name} must be a pytree prefix with bool leaves or a \"\n        f\"tuple-tree of bools \"\n        f\"(made of bools and tuples only), but {where} is {prefix!r} of type \"\n        f\"{type(prefix).__name__}\")\n  if treedef_is_strict_leaf(td):\n    raise ValueError(\n        f\"{full_name} must form a tree prefix of \"\n        f\"the corresponding values (up to pytree node types), but {where} is \"\n        \"a tuple while the corresponding part of the values is a leaf; use \"\n        \"a single bool there instead\")\n  td_children = td.children()\n  if len(prefix) != len(td_children):\n    raise ValueError(\n        f\"{full_name} must form a tree prefix of \"\n        \"the corresponding values (up to pytree node types, so containers \"\n        f\"need only match in their number of children), but {where} has \"\n        f\"{len(prefix)} children while the corresponding container has \"\n        f\"{len(td_children)}\")\n  for i, (p, td_) in enumerate(zip(prefix, td_children)):\n    _tuptree_flags_rec(p, td_, name, full_name, (*path, i), ret)\n\ndef _is_ref(x):\n  from jax._src.state.types import AbstractRef\n  try:\n    return isinstance(typeof(x), AbstractRef)\n  except:\n    return False\n\ndef _is_ref_aval(a):\n  from jax._src.state.types import AbstractRef\n  return isinstance(a, AbstractRef)","sourceCodeStart":1889,"sourceCodeEnd":1925,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/api.py#L1889-L1925","documentation":"The boolean prefix tuple must have the same number of children as the corresponding container in the values. JAX raises this when the tuple lengths diverge, meaning the prefix is not a valid tree prefix even though node kinds match.","triggerScenarios":"Passing (True,) against a values tuple of length 2, or (True, False, True) against a pair; any arity mismatch between prefix tuple and container.","commonSituations":"Adding/removing a return value from a function without updating the prefix; assuming a container has a different length (e.g. treating (a, b) as a 3-tuple).","solutions":["Inspect the values structure with jax.tree_util.tree_structure(values) and count children","Update the prefix tuple length to match the container's length","Use a single bool to broadcast over all children of that container"],"exampleFix":"// before\nprefix = (True,)          # values = (a, b)\n// after\nprefix = True             # or (True, False)","handlingStrategy":"validation","validationCode":"def prefix_len_ok(prefix, values):\n    if isinstance(prefix, bool): return True\n    return isinstance(values, tuple) and len(prefix) == len(values)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When function signatures change, recheck prefix arities","Write a small unit test asserting the prefix matches tree_structure of the values"],"tags":["jax","pytree","arity"],"backgroundTag":"pytree-structure-mismatch","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}