{"record":{"id":"24e098e8a84474e1","repo":"jax-ml/jax","slug":"mode-must-be-largest-or-smallest-got-mode-r","errorCode":null,"errorMessage":"mode must be 'largest' or 'smallest', got {mode!r}","messagePattern":"mode must be 'largest' or 'smallest', got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/numpy/sorting.py","lineNumber":509,"sourceCode":"    >>> indices\n    Array([[4, 3],\n           [0, 1]], dtype=int32)\n\n    Find the two smallest elements along the first axis:\n\n    >>> values, indices = jnp.top_k(a, 2, axis=0, mode='smallest')\n    >>> values\n    Array([[1, 2, 3, 2, 1],\n           [5, 4, 3, 4, 5]], dtype=int32)\n    >>> indices\n    Array([[0, 0, 0, 1, 1],\n           [1, 1, 1, 0, 0]], dtype=int32)\n  \"\"\"\n  arr = util.ensure_arraylike(\"top_k\", a)\n  if dtypes.issubdtype(arr.dtype, np.complexfloating):\n    raise ValueError(\"top_k is not compatible with complex inputs.\")\n  if mode not in (\"largest\", \"smallest\"):\n    raise ValueError(f\"mode must be 'largest' or 'smallest', got {mode!r}\")\n  axis = canonicalize_axis(axis, arr.ndim)\n  if mode == \"largest\":\n    return lax.top_k(arr, k, axis=axis)\n  elif dtypes.isdtype(arr.dtype, \"bool\"):\n    inv = lax.bitwise_not(arr)\n    vals, indices = lax.top_k(inv, k, axis=axis)\n    return lax.bitwise_not(vals), indices\n  elif dtypes.isdtype(arr.dtype, \"unsigned integer\"):\n    inv = -(arr + 1)\n    vals, indices = lax.top_k(inv, k, axis=axis)\n    return -(vals + 1), indices\n  else:\n    inv = -arr\n    vals, indices = lax.top_k(inv, k, axis=axis)\n    return -vals, indices\n","sourceCodeStart":491,"sourceCodeEnd":525,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/numpy/sorting.py#L491-L525","documentation":"jnp.top_k requires mode to be exactly the string 'largest' or 'smallest'; any other value raises ValueError with the offending value echoed. The validation happens after the complex-dtype check and before axis canonicalization, so it fires even for valid arrays.","triggerScenarios":"Calling jnp.top_k(a, k, mode='max'), mode='top', mode=None, or a typo like 'smalest'; also programmatic mode strings like 'top'/'bottom' that don't match the API.","commonSituations":"Assuming the API mirrors a different library's mode names (e.g., 'max'/'min' or 'top'/'bottom'); building mode from user config or CLI flags without validating against the allowed set; silent typos.","solutions":["Use exactly 'largest' or 'smallest' as the mode string","Map external mode names at the boundary: {'max': 'largest', 'min': 'smallest'}","Validate/normalize mode strings from config before passing them in"],"exampleFix":"# before\nvals, idx = jnp.top_k(x, 5, mode='max')\n# after\nvals, idx = jnp.top_k(x, 5, mode='largest')","handlingStrategy":"validation","validationCode":"assert mode in ('largest', 'smallest'), f\"invalid top_k mode: {mode!r}\"","typeGuard":"def is_valid_top_k_mode(mode: str) -> bool:\n    return mode in ('largest', 'smallest')","tryCatchPattern":null,"preventionTips":["Map external vocab to JAX modes at the API boundary","Use a Literal['largest','smallest'] type hint for mode","Normalize case/typos in config parsing"],"tags":["jax","top-k","invalid-argument","value-error","enum-validation"],"backgroundTag":"invalid-enum-argument","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}