{"record":{"id":"e20c3b8ed9a8efe4","repo":"xai-org/x-algorithm","slug":"cap-method-must-be-in-tanh-soft-sign-got-cap","errorCode":null,"errorMessage":"cap_method must be in [tanh, soft_sign], got {cap_method}","messagePattern":"cap_method must be in \\[tanh, soft_sign\\], got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/pallas/ranker_attention.py","lineNumber":94,"sourceCode":"        seg_k = pl.load(\n            segment_ref,\n            (pl.dslice(start_k * block_k, block_k),),\n        )\n        temp = pl.load(temp_ref, (pl.dslice(start_q * block_q, block_q),))\n        temp = jnp.expand_dims(temp, axis=-1)\n        mask = jnp.equal(jnp.zeros_like(seg_q), jnp.expand_dims(seg_k, axis=-2))\n        qk = jnp.zeros([block_q, block_k], dtype=jnp.float32)\n        qk += pl.dot(q, k)\n        if sm_scale != 1.0:\n            qk *= sm_scale\n\n        if cap > 0.0:\n            if cap_method == \"tanh\":\n                qk = cap * tanh(qk / cap)\n            elif cap_method == \"soft_sign\":\n                qk = qk / (1.0 + jnp.abs(qk) / cap)\n            else:\n                raise ValueError(f\"cap_method must be in [tanh, soft_sign], got {cap_method}\")\n        qk = qk * temp\n        span_q = start_q * block_q + jnp.arange(block_q)\n        span_k = start_k * block_k + jnp.arange(block_k)\n        if causal:\n            causal_mask = span_q[:, None] >= (span_k[None, :] + inverted_sliding_window_sizep1)\n            mask = jnp.logical_and(causal_mask, mask)\n        mask = jnp.logical_or(mask, span_q[:, None] == span_k[None, :])\n        if window_len > 0:\n            window_mask = span_k[None, :] > span_q[:, None] - window_len\n            mask = jnp.logical_and(mask, window_mask)\n\n        padding_mask = jnp.logical_and(seg_q != 2, jnp.expand_dims(seg_k != 2, axis=-2))\n        mask = jnp.logical_and(mask, padding_mask)\n\n        qk = jnp.where(mask, qk, DEFAULT_MASK_VALUE)\n        m_curr = jnp.maximum(jnp.max(qk, axis=1), m_prev)\n        l_new = jnp.exp(m_prev - m_curr)\n        l_new = jax.lax.select(jnp.isnan(l_new), jnp.ones_like(l_new), l_new)","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/pallas/ranker_attention.py#L76-L112","documentation":"The ranker attention forward kernel caps logits (qk) before the softmax using either tanh or soft_sign squashing. If cap_method is not one of these two strings, the kernel body raises this ValueError inside the Pallas program.","triggerScenarios":"Calling the ranker attention kernel with cap > 0.0 and cap_method set to an unrecognized value (e.g. 'sigmoid', 'clip', or a typo). Note cap_method == 0 disables capping only when cap <= 0.0.","commonSituations":"Config typos, copying config from another attention implementation with different capping names, or defaulting cap_method to None while setting cap > 0.","solutions":["Set cap_method to 'tanh' or 'soft_sign'","If you want no capping, set cap=0.0 so the capping branch is skipped entirely","Add config validation for cap_method before launching the kernel (Pallas errors inside kernels are hard to debug)"],"exampleFix":"# before\nattn_out = ranker_attention(q, k, v, cap=10.0, cap_method=\"clamp\")\n\n# after\nattn_out = ranker_attention(q, k, v, cap=10.0, cap_method=\"tanh\")","handlingStrategy":"validation","validationCode":"if cap > 0.0:\n    assert cap_method in (\"tanh\", \"soft_sign\"), f\"bad cap_method={cap_method!r}\"","typeGuard":"def valid_cap_method(m: str) -> bool:\n    return m in (\"tanh\", \"soft_sign\")","tryCatchPattern":null,"preventionTips":["Validate cap/cap_method pairs in config loading","Add a unit test exercising the attention op end-to-end (fwd+bwd) to catch bad kwargs early"],"tags":["attention","pallas","logit-capping","invalid-argument","ranker"],"backgroundTag":"invalid-enum-value","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}