What causes "Random walk steps must be greater than 0" in mastra-ai/mastra?

Pass a positive integer for randomWalkSteps (e.g. 10-100 is typical)

Random walk steps must be greater than 0

Error message

Random walk steps must be greater than 0

What it means

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.

Source

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

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

    // Sort by similarity

View on GitHub (pinned to 75dd419e61)

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

Example fix

// before
await graphRag.query({ query: 'q', topK: 10, randomWalkSteps: 0 });
// after
await graphRag.query({ query: 'q', topK: 10, randomWalkSteps: 50 });

Defensive patterns

Strategy: validation

Validate before calling

if (!Number.isInteger(randomWalkSteps) || randomWalkSteps < 1) throw new RangeError('randomWalkSteps must be >= 1');

Type guard

const isValidSteps = (n: unknown): n is number => typeof n === 'number' && Number.isInteger(n) && n >= 1;

Try / catch

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

Prevention

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

When it happens

Trigger: Calling graphRag.query({ query, topK, randomWalkSteps: 0 }) or any negative value, directly or via the GraphRAGTool when randomWalkSteps is configured as 0.

Common situations: Copy-pasted config with randomWalkSteps: 0 intending 'use default'; computing steps dynamically and getting 0; passing options objects where the field defaulted to 0.

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

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