{"record":{"id":"6c33cda534addaf1","repo":"mastra-ai/mastra","slug":"restart-probability-must-be-between-0-and-1","errorCode":null,"errorMessage":"Restart probability must be between 0 and 1","messagePattern":"Restart probability must be between 0 and 1","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/graph-rag/index.ts","lineNumber":360,"sourceCode":"    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\n    similarities.sort((a, b) => b.similarity - a.similarity);\n    const topNodes = similarities.slice(0, topK);\n","sourceCodeStart":342,"sourceCodeEnd":378,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/graph-rag/index.ts#L342-L378","documentation":"GraphRAG.query() requires restartProb to be strictly between 0 and 1 (exclusive). This probability controls how often the random walk restarts from the query node; 0 or 1 (or out-of-range values) would break the walk semantics, so the library rejects them.","triggerScenarios":"Calling graphRag.query({ ..., restartProb: 0 }), restartProb: 1, or any negative value / value > 1, including via requestContext/graphOptions on the GraphRAGTool.","commonSituations":"Typo like restartProb: 1.5; misreading docs and passing a percentage like 15 instead of 0.15; defaulting the value to 0 in config code.","solutions":["Use a value strictly between 0 and 1, e.g. 0.2-0.5","Convert percentages to fractions (15% -> 0.15)","Clamp the computed value: Math.min(0.99, Math.max(0.01, restartProb))"],"exampleFix":"// before\nawait graphRag.query({ query: 'q', topK: 10, restartProb: 1 });\n// after\nawait graphRag.query({ query: 'q', topK: 10, restartProb: 0.3 });","handlingStrategy":"validation","validationCode":"if (typeof restartProb !== 'number' || restartProb <= 0 || restartProb >= 1) throw new RangeError('restartProb must be in (0, 1)');","typeGuard":"const isValidProb = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n > 0 && n < 1;","tryCatchPattern":"try { await graphRag.query(args); } catch (e) { if (e instanceof Error && e.message.includes('Restart probability')) { args.restartProb = 0.3; return graphRag.query(args); } throw e; }","preventionTips":["Store probabilities as fractions, never percentages","Clamp computed values into (0,1) before calling","Document the exclusive bounds where the constant is defined"],"tags":["validation","parameters","graph-rag"],"backgroundTag":"invalid-parameter-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}