{"record":{"id":"efe2028e104bd055","repo":"xai-org/x-algorithm","slug":"cap-method-must-be-in-tanh-soft-sign-got-cap-efe202","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_varlen.py","lineNumber":282,"sourceCode":"        )\n        seg_k = pl.load(\n            segment_ref,\n            (pl.dslice(offset_k, block_k),),\n            mask=k_mask,\n            other=PADDING_SEGMENT_ID,\n        ).astype(jnp.int8)[None, :]\n\n        qk = pl.dot(q, k, trans_b=True)\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\n        mask = jnp.logical_or(seg_k > 0, span_q[:, None] == span_k[None, :])\n        mask = jnp.logical_and(seq_q_is_not_padding, mask)\n        mask = jnp.logical_and(mask, k_mask[None, :])\n\n        if causal:\n            causal_mask = span_q[:, None] >= span_k[None, :]\n            mask = jnp.logical_and(mask, causal_mask)\n\n        qk = jnp.where(mask, qk, DEFAULT_MASK_VALUE)\n        max_logit = jnp.max(qk, axis=1)\n        max_logit = jnp.maximum(max_logit, 1.0)\n        m_curr = jnp.maximum(m_prev, max_logit)\n        p = jnp.exp(qk - m_curr[:, None])\n        alpha = jnp.exp(m_prev - m_curr)\n        l_prev = l_prev * alpha + jnp.sum(p, axis=1)\n\n        p = p.astype(q.dtype)","sourceCodeStart":264,"sourceCodeEnd":300,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/pallas/ranker_attention_varlen.py#L264-L300","documentation":"The varlen ranker attention forward kernel applies logit capping when cap > 0.0 and only implements 'tanh' and 'soft_sign' methods; any other cap_method string triggers this guard inside the scan body. It mirrors the v2 kernel's validation and indicates a bad hyperparameter reaching the kernel.","triggerScenarios":"Calling varlen ranker attention with cap > 0.0 and cap_method not in ['tanh', 'soft_sign'].","commonSituations":"Hyperparameter sweeps with unsupported capping names; configs ported from FlashAttention-style APIs that use different cap method names; typos/case errors.","solutions":["Use cap_method='tanh' or cap_method='soft_sign'.","Disable capping with cap=0.0 if that was the intent.","Validate cap_method in config parsing before kernel launch."],"exampleFix":"# before\nattn_varlen(..., cap=50.0, cap_method='sinh')\n# after\nattn_varlen(..., cap=50.0, cap_method='tanh')","handlingStrategy":"validation","validationCode":"assert cap <= 0.0 or cap_method in ('tanh', 'soft_sign')","typeGuard":"from typing import Literal\nCapMethod = Literal['tanh', 'soft_sign']\ndef is_valid_cap_method(s: str) -> bool:\n    return s in ('tanh', 'soft_sign')","tryCatchPattern":null,"preventionTips":["Centralize cap_method as a validated Literal in config dataclasses.","Reject unknown strings at config parse time with a helpful message."],"tags":["pallas","jax","tpu","attention","config-validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}