{"record":{"id":"40a5a3d0265c419f","repo":"mastra-ai/mastra","slug":"random-walk-steps-must-be-greater-than-0","errorCode":null,"errorMessage":"Random walk steps must be greater than 0","messagePattern":"Random walk steps must be greater than 0","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/graph-rag/index.ts","lineNumber":357,"sourceCode":"    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\n    const similarities = nodesToSearch.map(node => ({\n      node,\n      similarity: this.cosineSimilarity(query, node.embedding!),\n    }));\n\n    // Sort by similarity","sourceCodeStart":339,"sourceCodeEnd":375,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/graph-rag/index.ts#L339-L375","documentation":"GraphRAG.query() validates all numeric parameters before executing the random-walk search. This error means randomWalkSteps was less than 1 (e.g. 0 or a negative number). The library requires at least one random-walk step to traverse the graph, so non-positive values are rejected up front instead of silently returning empty results.","triggerScenarios":"Calling graphRag.query({ query, topK, randomWalkSteps: 0 }) or any negative value, directly or via the GraphRAGTool when randomWalkSteps is configured as 0.","commonSituations":"Copy-pasted config with randomWalkSteps: 0 intending 'use default'; computing steps dynamically and getting 0; passing options objects where the field defaulted to 0.","solutions":["Pass a positive integer for randomWalkSteps (e.g. 10-100 is typical)","Omit randomWalkSteps if the API supports a default instead of passing 0","Fix the code computing the value so it yields >= 1"],"exampleFix":"// before\nawait graphRag.query({ query: 'q', topK: 10, randomWalkSteps: 0 });\n// after\nawait graphRag.query({ query: 'q', topK: 10, randomWalkSteps: 50 });","handlingStrategy":"validation","validationCode":"if (!Number.isInteger(randomWalkSteps) || randomWalkSteps < 1) throw new RangeError('randomWalkSteps must be >= 1');","typeGuard":"const isValidSteps = (n: unknown): n is number => typeof n === 'number' && Number.isInteger(n) && n >= 1;","tryCatchPattern":"try { await graphRag.query(args); } catch (e) { if (e instanceof Error && e.message.includes('Random walk steps')) { /* fix args or use default */ } else throw e; }","preventionTips":["Use defaults or omit the option instead of hardcoding 0","Validate numeric options at config load time","Add a unit test asserting the tool config yields randomWalkSteps >= 1"],"tags":["validation","parameters","graph-rag"],"backgroundTag":"invalid-parameter-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}