xai-org/x-algorithm · error · ValueError

cap_method must be in [tanh, soft_sign, none], got {cap_meth

Error message

cap_method must be in [tanh, soft_sign, none], got {cap_method}

What it means

_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.

Source

Thrown at phoenix/xrex/pallas/ranker_attention_fa3.py:40

def tanh(x):
    return 2 * jax.lax.logistic(2 * x) - 1


def _abs(x):
    return jnp.where(x >= 0, x, -x)


def _apply_cap(qk, cap: float, cap_method: str):
    if cap <= 0.0 or cap_method == "none":
        return qk, None, None
    if cap_method == "tanh":
        qk_tanh = tanh(qk / cap)
        return cap * qk_tanh, qk_tanh, None
    if cap_method == "soft_sign":
        soft_sign = 1.0 / (1.0 + _abs(qk) / cap)
        return qk * soft_sign, None, soft_sign
    raise ValueError(f"cap_method must be in [tanh, soft_sign, none], got {cap_method}")


@dataclasses.dataclass(frozen=True)
class TuningConfig:
    block_q: int
    block_kv: int
    max_concurrent_steps: int
    use_schedule_barrier: bool = True
    causal: bool = False
    compute_wgs_bwd: int = 1

    block_q_dkv: int | None = None
    block_kv_dkv: int | None = None
    block_q_dq: int | None = None
    block_kv_dq: int | None = None

    def __post_init__(self):
        if self.block_q % 64:

View on GitHub (pinned to 24c60942c5)

Solutions

1. Use 'tanh' or 'soft_sign' when capping is active
2. Use 'none' (or disable cap) when no capping is wanted
3. Validate cap_method against the allowed set at config load time

Example fix

// before
attention(q, k, v, cap=50.0, cap_method="sigmoid")
// after
attention(q, k, v, cap=50.0, cap_method="soft_sign")

if cap > 0:
    assert cap_method in {"tanh", "soft_sign"}, f"bad cap_method: {cap_method}"

null

When it happens

Trigger: 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').

Common situations: Config drift between this module and ranker_attention.mha_reference, user-defined YAML configs with a renamed capping option, typos.

Related errors

• cap_method must be in [tanh, soft_sign], got {cap_method}
• cap_method must be in [tanh, soft_sign]
• Invalid backward pass implementation: {backward_pass_impl}
• q, k, and v should all be 4D, got: {q.ndim=}, {k.ndim=}, {v.
• {head_dim=} must be divisible by 64

AI-assisted analysis of xai-org/x-algorithm@24c60942c5 (2026-08-28). Data as JSON: /api/errors/be7569b1f7acbcb4. Report an issue: GitHub.