FlashAttention: Key and value dimensions must match. Got K=$

Error message

FlashAttention: Key and value dimensions must match. Got K=${kDim}, V=${vDim}

What it means

After the Q/K check, validateInputs() also requires values[0].length === keys[0].length — in this implementation V must have the same per-vector dimension as K, and any difference throws with both numbers. This is stricter than attention APIs (e.g. PyTorch) that allow an independent value/output dimension d_v, which is the most common reason ported code trips it.

Source

Thrown at v3/@claude-flow/neural/src/flash-attention.ts:791

    if (keys.length !== values.length) {
      throw new Error(
        `FlashAttention: Keys and values must have same count. Got ${keys.length} keys, ${values.length} values`,
      );
    }

    const qDim = queries[0]?.length ?? 0;
    const kDim = keys[0]?.length ?? 0;
    const vDim = values[0]?.length ?? 0;

    if (qDim !== kDim) {
      throw new Error(
        `FlashAttention: Query and key dimensions must match. Got Q=${qDim}, K=${kDim}`,
      );
    }

    if (kDim !== vDim) {
      throw new Error(
        `FlashAttention: Key and value dimensions must match. Got K=${kDim}, V=${vDim}`,
      );
    }
  }
}

// ============================================================================
// Singleton Instance
// ============================================================================

let flashAttentionInstance: FlashAttention | null = null;

/**
 * Get singleton FlashAttention instance
 *
 * @param config - Optional configuration (only used on first call)
 * @returns FlashAttention instance
 */

View on GitHub (pinned to fa13ee4ad6)

Solutions

Make values the same dimension as keys (derive all three tensors from the same encoder output)
Project or pad values to the key dimension if the pipeline genuinely produces a different width
Re-encode K and V together from one tensor so dims cannot drift

Example fix

// before
const out = computeAttention(q, k, v /* v is 256-dim, k is 384-dim */);

// after
const vProjected = project(v, k[0].length); // widen/narrow V to match K
const out = computeAttention(q, k, vProjected);

Defensive patterns

Strategy: validation

Validate before calling

const kDim = keys[0]?.length ?? 0;
const vDim = values[0]?.length ?? 0;
if (kDim !== vDim) {
  throw new Error(`K/V dimension mismatch: ${kDim} vs ${vDim} - this implementation requires d_v === d_k`);
}
const out = computeAttention(queries, keys, values);

Prevention

Do not port d_v != d_k transformer configs directly - this API requires equal dims
Build K and V from the same encoder output so dimensions cannot drift
Project or pad values to the key dimension when bridging different feature widths

When it happens

Trigger: Porting attention code from a framework where d_v differs from d_k; building values from a different feature source than keys; stale cached values after a dimension change on keys.

Common situations: Migrating transformer code from PyTorch/transformers.js; pipelines where values carry auxiliary features of another width.

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/7d723a6edce255f4. Report an issue: GitHub.