mastra-ai/mastra · error

Vector dimensions must match: vec1

Error message

Vector dimensions must match: vec1(${vec1.length}) !== vec2(${vec2.length})

What it means

cosineSimilarity requires both vectors to have identical length; it throws with the two mismatched lengths otherwise. Since node embeddings and query embeddings can come from different embedding models, dimension drift between them triggers this inside query().

Solutions

1. Rebuild the graph with createGraph using embeddings from the same model you will query with.
2. Make the query embedding dimension match the GraphRAG constructor dimension (default 1536).
3. Pin a single embedding model across indexing and query code paths and record it in metadata.
4. Validate vector lengths client-side before calling query().

Example fix

// before
const results = graph.query({ query: await embed(text) });
// after
const q = await embed(text); // same model used at index time
if (q.length !== 1536) throw new Error(`Rebuild index: embedding dim ${q.length} != 1536`);
const results = graph.query({ query: q });

const dim = 1536; // dimension of the model used at index time
if (!Array.isArray(query) || query.length !== dim) {
  throw new Error(`Query vector must be ${dim}-dim; got ${query?.length}`);
}

const hasCorrectDimension = (v: unknown, dim: number): v is number[] =>
  Array.isArray(v) && v.length === dim && v.every(x => typeof x === 'number');

try {
  const results = graph.query({ query });
} catch (e) {
  if ((e as Error).message.startsWith('Vector dimensions must match')) {
    // embedding model drift: rebuild the graph with the current model
  } else throw e;
}

When it happens

Trigger: Querying a graph built with one embedding model/dimension using a query vector of another dimension (e.g. 1536 vs 768 vs 3072); createGraph with ragged embedding arrays of unequal lengths.

Common situations: Switching embedding providers (OpenAI text-embedding-3-small 1536 -> large 3072, or a 768-dim local model) without rebuilding the index; configuring the wrong model in one environment; passing un-truncated variable-length vectors.

Related errors

• Embedding dimension must be
• Query embedding must have dimension
• Vectors must not be null or undefined
• Chunks and embeddings arrays must not be empty
• Chunks and embeddings must have the same length

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/5f2b687b99b4b077. Report an issue: GitHub.

Appendix: source

Thrown at packages/rag/src/graph-rag/index.ts:200

  private getNeighbors(nodeId: string, edgeType?: string): { id: string; weight: number }[] {
    return this.edges
      .filter(edge => edge.source === nodeId && (!edgeType || edge.type === edgeType))
      .map(edge => ({
        id: edge.target,
        weight: edge.weight,
      }))
      .filter(node => node !== undefined);
  }

  // Calculate cosine similarity between two vectors
  private cosineSimilarity(vec1: number[], vec2: number[]): number {
    if (!vec1 || !vec2) {
      throw new Error('Vectors must not be null or undefined');
    }
    const vectorLength = vec1.length;

    if (vectorLength !== vec2.length) {
      throw new Error(`Vector dimensions must match: vec1(${vec1.length}) !== vec2(${vec2.length})`);
    }

    let dotProduct = 0;
    let normVec1 = 0;
    let normVec2 = 0;

    for (let i = 0; i < vectorLength; i++) {
      const a = vec1[i]!; // Non-null assertion operator
      const b = vec2[i]!;

      dotProduct += a * b;
      normVec1 += a * a;
      normVec2 += b * b;
    }
    const magnitudeProduct = Math.sqrt(normVec1 * normVec2);

    if (magnitudeProduct === 0) {
      return 0;

View on GitHub (pinned to 75dd419e61)