mastra-ai/mastra · error

Restart probability must be between 0 and 1

Error message

Restart probability must be between 0 and 1

What it means

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.

Source

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

    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
    const similarities = nodesToSearch.map(node => ({
      node,
      similarity: this.cosineSimilarity(query, node.embedding!),
    }));

    // Sort by similarity
    similarities.sort((a, b) => b.similarity - a.similarity);
    const topNodes = similarities.slice(0, topK);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a value strictly between 0 and 1, e.g. 0.2-0.5
2. Convert percentages to fractions (15% -> 0.15)
3. Clamp the computed value: Math.min(0.99, Math.max(0.01, restartProb))

Example fix

// before
await graphRag.query({ query: 'q', topK: 10, restartProb: 1 });
// after
await graphRag.query({ query: 'q', topK: 10, restartProb: 0.3 });

if (typeof restartProb !== 'number' || restartProb <= 0 || restartProb >= 1) throw new RangeError('restartProb must be in (0, 1)');

const isValidProb = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n > 0 && n < 1;

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; }

When it happens

Trigger: Calling graphRag.query({ ..., restartProb: 0 }), restartProb: 1, or any negative value / value > 1, including via requestContext/graphOptions on the GraphRAGTool.

Common situations: 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.

Understand the failure class

Background: "must be positive", "Invalid value": how libraries reject invalid parameter values (ValueError, ArgumentError, INVALID_PARAMETER_VALUE) — this error's family across 28 libraries.

Related errors

• Random walk steps must be greater than 0
• language must be a two-letter code (e.g. "en", "es")
• Node must have an embedding
• Both source and target nodes must exist
• indexName is required, got: ${indexName}

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