{"record":{"id":"be7569b1f7acbcb4","repo":"xai-org/x-algorithm","slug":"cap-method-must-be-in-tanh-soft-sign-none-got","errorCode":null,"errorMessage":"cap_method must be in [tanh, soft_sign, none], got {cap_method}","messagePattern":"cap_method must be in \\[tanh, soft_sign, none\\], got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/pallas/ranker_attention_fa3.py","lineNumber":40,"sourceCode":"\ndef tanh(x):\n    return 2 * jax.lax.logistic(2 * x) - 1\n\n\ndef _abs(x):\n    return jnp.where(x >= 0, x, -x)\n\n\ndef _apply_cap(qk, cap: float, cap_method: str):\n    if cap <= 0.0 or cap_method == \"none\":\n        return qk, None, None\n    if cap_method == \"tanh\":\n        qk_tanh = tanh(qk / cap)\n        return cap * qk_tanh, qk_tanh, None\n    if cap_method == \"soft_sign\":\n        soft_sign = 1.0 / (1.0 + _abs(qk) / cap)\n        return qk * soft_sign, None, soft_sign\n    raise ValueError(f\"cap_method must be in [tanh, soft_sign, none], got {cap_method}\")\n\n\n@dataclasses.dataclass(frozen=True)\nclass TuningConfig:\n    block_q: int\n    block_kv: int\n    max_concurrent_steps: int\n    use_schedule_barrier: bool = True\n    causal: bool = False\n    compute_wgs_bwd: int = 1\n\n    block_q_dkv: int | None = None\n    block_kv_dkv: int | None = None\n    block_q_dq: int | None = None\n    block_kv_dq: int | None = None\n\n    def __post_init__(self):\n        if self.block_q % 64:","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/pallas/ranker_attention_fa3.py#L22-L58","documentation":"_apply_cap in the FA3-style ranker attention supports three cap methods: 'tanh', 'soft_sign', and 'none' (implicit — any other value that isn't matched raises, though the message says none is allowed; 'none' is handled by the caller skipping capping). The error fires when the qk logits capping function name is unrecognized.","triggerScenarios":"Calling attention/kv_loop/q_pipeline/attention_reference with cap > 0 and a cap_method string other than 'tanh' or 'soft_sign' (e.g. 'sigmoid', 'clamp').","commonSituations":"Config drift between this module and ranker_attention.mha_reference, user-defined YAML configs with a renamed capping option, typos.","solutions":["Use 'tanh' or 'soft_sign' when capping is active","Use 'none' (or disable cap) when no capping is wanted","Validate cap_method against the allowed set at config load time"],"exampleFix":"// before\nattention(q, k, v, cap=50.0, cap_method=\"sigmoid\")\n// after\nattention(q, k, v, cap=50.0, cap_method=\"soft_sign\")","handlingStrategy":"validation","validationCode":"if cap > 0:\n    assert cap_method in {\"tanh\", \"soft_sign\"}, f\"bad cap_method: {cap_method}\"","typeGuard":"null","tryCatchPattern":null,"preventionTips":["Validate cap_method once at config parse time","Keep capping configs in one place shared by all attention variants"],"tags":["jax","pallas","attention","logit-capping"],"backgroundTag":"invalid-enum-argument","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}