FlashAttention: Query and key dimensions must match. Got Q=$

Error message

FlashAttention: Query and key dimensions must match. Got Q=${qDim}, K=${kDim}

What it means

The QK^T dot product requires query and key vectors of equal dimension; validateInputs() compares the length of queries[0] and keys[0] and throws with both dims on mismatch. Note it inspects only the first vectors — all vectors are assumed uniform within each set, so a single stray vector of another width can also corrupt results without tripping this check.

Source

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

    keys: Float32Array[],
    values: Float32Array[],
  ): void {
    if (!queries.length || !keys.length || !values.length) {
      throw new Error('FlashAttention: Empty input arrays');
    }

    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;

View on GitHub (pinned to fa13ee4ad6)

Solutions

Use the same embedding dimension (same model/config) for queries and keys
Project one side to the other's dimension before calling attention
Log qDim/kDim at startup in adapters that bridge two models

Example fix

// before
const out = computeAttention(queries384, keys768, values768);

// after
// re-encode queries with the same model as keys (768-dim)
const out = computeAttention(queries768, keys768, values768);

Defensive patterns

Strategy: validation

Validate before calling

const qDim = queries[0]?.length ?? 0;
const kDim = keys[0]?.length ?? 0;
if (qDim !== kDim) {
  throw new Error(`Q/K dimension mismatch: ${qDim} vs ${kDim} - re-encode with one model`);
}
const out = computeAttention(queries, keys, values);

Prevention

Use one embedding model for queries and keys
Invalidate cached embeddings when the encoder changes
Log tensor dims at adapter boundaries to catch mismatches early

When it happens

Trigger: Queries produced by a different embedding model than keys (e.g. 384-dim Q vs 768-dim K after a model swap); mixing outputs of two encoders; a head_dim config change applied to only one side.

Common situations: Upgrading an ONNX embedding model without regenerating cached tensors; mixing fresh and cached embeddings; hand-written test fixtures with mismatched dims.

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/51c65df71581d42f. Report an issue: GitHub.