{"record":{"id":"67c8b4bc4035dbaa","repo":"mastra-ai/mastra","slug":"query-embedding-must-have-dimension-this-dimensi","errorCode":null,"errorMessage":"Query embedding must have dimension ${this.dimension}","messagePattern":"Query embedding must have dimension (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/graph-rag/index.ts","lineNumber":351,"sourceCode":"   * @param restartProb - Restart probability for random walk.\n   * @param filter - Optional strict metadata filter. All key-value pairs must match exactly.\n   */\n  // Retrieve relevant nodes using hybrid approach\n  query({\n    query,\n    topK = 10,\n    randomWalkSteps = 100,\n    restartProb = 0.15,\n    filter,\n  }: {\n    query: number[];\n    topK?: number;\n    randomWalkSteps?: number;\n    restartProb?: number;\n    filter?: Partial<GraphMetadata>;\n  }): RankedNode[] {\n    if (!query || query.length !== this.dimension) {\n      throw new Error(`Query embedding must have dimension ${this.dimension}`);\n    }\n    if (topK < 1) {\n      throw new Error('TopK must be greater than 0');\n    }\n    if (randomWalkSteps < 1) {\n      throw new Error('Random walk steps must be greater than 0');\n    }\n    if (restartProb <= 0 || restartProb >= 1) {\n      throw new Error('Restart probability must be between 0 and 1');\n    }\n\n    const filterEntries = Object.entries(filter ?? {});\n    const matchesFilter = (node: GraphNode) =>\n      filterEntries.length === 0 ? true : filterEntries.every(([key, value]) => node.metadata?.[key] === value);\n\n    const nodesToSearch = Array.from(this.nodes.values()).filter(matchesFilter);\n\n    // Retrieve nodes and calculate similarity","sourceCodeStart":333,"sourceCodeEnd":369,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/graph-rag/index.ts#L333-L369","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst res = graph.query({ query: vector });\n// after\nif (!Array.isArray(vector) || vector.length !== 1536) {\n  throw new Error(`Query vector must be 1536-dim, got ${vector?.length}`);\n}\nconst res = graph.query({ query: vector });","handlingStrategy":"validation","validationCode":"const dim = 1536; // must match new GraphRAG(dim)\nif (!Array.isArray(query) || query.length !== dim) {\n  throw new Error(`query() needs a ${dim}-dim vector; got ${query?.length ?? 'null'}`);\n}","typeGuard":"const isQueryVector = (v: unknown, dim: number): v is number[] =>\n  Array.isArray(v) && v.length === dim;","tryCatchPattern":"try {\n  const results = graph.query({ query: qv, topK: 5 });\n} catch (e) {\n  if ((e as Error).message.startsWith('Query embedding must have dimension')) {\n    // embed the query with the index's model, or rebuild the index\n  } else throw e;\n}","preventionTips":["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"],"tags":["rag","dimension-mismatch","embedding","query"],"backgroundTag":"vector-dimension-mismatch","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}