Query embedding must have dimension ${this.dimension}

Error message

Query embedding must have dimension ${this.dimension}

What it means

query() validates that the provided query embedding is a non-empty array whose length equals the graph's dimension (set at construction, default 1536). It throws otherwise, before any similarity computation, because cosine similarity is undefined across dimensions.

Source

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

   * @param restartProb - Restart probability for random walk.
   * @param filter - Optional strict metadata filter. All key-value pairs must match exactly.
   */
  // Retrieve relevant nodes using hybrid approach
  query({
    query,
    topK = 10,
    randomWalkSteps = 100,
    restartProb = 0.15,
    filter,
  }: {
    query: number[];
    topK?: number;
    randomWalkSteps?: number;
    restartProb?: number;
    filter?: Partial<GraphMetadata>;
  }): RankedNode[] {
    if (!query || query.length !== this.dimension) {
      throw new Error(`Query embedding must have dimension ${this.dimension}`);
    }
    if (topK < 1) {
      throw new Error('TopK must be greater than 0');
    }
    if (randomWalkSteps < 1) {
      throw new Error('Random walk steps must be greater than 0');
    }
    if (restartProb <= 0 || restartProb >= 1) {
      throw new Error('Restart probability must be between 0 and 1');
    }

    const filterEntries = Object.entries(filter ?? {});
    const matchesFilter = (node: GraphNode) =>
      filterEntries.length === 0 ? true : filterEntries.every(([key, value]) => node.metadata?.[key] === value);

    const nodesToSearch = Array.from(this.nodes.values()).filter(matchesFilter);

    // Retrieve nodes and calculate similarity

View on GitHub (pinned to 75dd419e61)

Solutions

Embed the query with the same model used to build the graph so dimensions match.
Pass the correct dimension to new GraphRAG(dimension) to match your embedding model.
Validate Array.isArray(query) && query.length === dimension before calling query().
Check that the embed call actually returned a vector, not an empty array or undefined.

Example fix

// before
const res = graph.query({ query: vector });
// after
if (!Array.isArray(vector) || vector.length !== 1536) {
  throw new Error(`Query vector must be 1536-dim, got ${vector?.length}`);
}
const res = graph.query({ query: vector });

Defensive patterns

Strategy: validation

Validate before calling

const dim = 1536; // must match new GraphRAG(dim)
if (!Array.isArray(query) || query.length !== dim) {
  throw new Error(`query() needs a ${dim}-dim vector; got ${query?.length ?? 'null'}`);
}

Type guard

const isQueryVector = (v: unknown, dim: number): v is number[] =>
  Array.isArray(v) && v.length === dim;

Try / catch

try {
  const results = graph.query({ query: qv, topK: 5 });
} catch (e) {
  if ((e as Error).message.startsWith('Query embedding must have dimension')) {
    // embed the query with the index's model, or rebuild the index
  } else throw e;
}

Prevention

Use the same embedding model for queries and documents
Set GraphRAG's dimension explicitly to your model's output size
Check embed() returns a real vector (non-empty array), not undefined/[]
Never pass raw text where an embedding vector is expected

When it happens

Trigger: graph.query({ query }) with query null/undefined, an empty array, or a vector whose length differs from new GraphRAG(dimension)'s dimension — most often a query embedded by a different model than the index.

Common situations: Switching embedding models between indexing and querying; calling query with raw text instead of an embedding; default dimension 1536 assumed but a 768/384-dim model configured; empty array from a failed embed call.

Related errors

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