mastra-ai/mastra · error

indexName is required, got: ${indexName}

Error message

indexName is required, got: ${indexName}

What it means

createGraphRAGTool's execute resolves indexName from requestContext or tool options; if both are empty/undefined it throws this error naming the received value. A graph RAG query cannot run without knowing which vector index to search.

Source

Thrown at packages/rag/src/tools/graph-rag.ts:52

  const inputSchema = options.enableFilter ? filterSchema : z.object(baseSchema).passthrough();

  return createTool({
    id: toolId,
    inputSchema,
    outputSchema,
    description: toolDescription,
    execute: async (inputData, context) => {
      // See vector-query.ts for the same pattern: `context` from `createTool`
      // is loosely typed; cast is safe because `createObservabilityContext`
      // falls back to `noOpTracingContext` when `tracingContext` is undefined.
      const { requestContext, mastra, tracingContext } = (context as any) || {};
      const observabilityContext = createObservabilityContext(tracingContext);
      const parentSpan = observabilityContext.tracingContext?.currentSpan;
      const indexName: string = requestContext?.get('indexName') ?? options.indexName;
      const vectorStoreName: string =
        'vectorStore' in options ? storeName : (requestContext?.get('vectorStoreName') ?? storeName);
      if (!indexName) throw new Error(`indexName is required, got: ${indexName}`);
      if (!vectorStoreName) throw new Error(`vectorStoreName is required, got: ${vectorStoreName}`);
      const includeSources: boolean = requestContext?.get('includeSources') ?? options.includeSources ?? true;
      const randomWalkSteps: number | undefined =
        requestContext?.get('randomWalkSteps') ?? graphOptions.randomWalkSteps;
      const restartProb: number | undefined = requestContext?.get('restartProb') ?? graphOptions.restartProb;
      const topK: number = requestContext?.get('topK') ?? (inputData.topK as number) ?? 10;
      const filter: unknown = requestContext?.get('filter') ?? inputData.filter;
      const queryText = inputData.queryText;
      const providerOptions: ProviderOptions['providerOptions'] =
        requestContext?.get('providerOptions') ?? options.providerOptions;

      const enableFilter = !!requestContext?.get('filter') || (options.enableFilter ?? false);

      const logger = mastra?.getLogger();
      if (logger) {
        logger.debug('[GraphRAGTool] execute called with:', { queryText, topK, filter });
      }
      try {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass indexName in createGraphRAGTool options: { vectorStore, indexName: 'my-index', ... }
2. If using requestContext, ensure the middleware sets 'indexName' before execute
3. Check the interpolated value in the message to see whether it was undefined or an empty string and fix the source

Example fix

// before
const tool = createGraphRAGTool({ vectorStore, model });
// after
const tool = createGraphRAGTool({ vectorStore, indexName: 'my-index', model });

const indexName = requestContext?.get('indexName') ?? options.indexName;
if (!indexName) throw new Error('createGraphRAGTool: indexName must be provided');

const hasIndexName = (o: unknown): o is { indexName: string } => typeof o === 'object' && o !== null && typeof (o as any).indexName === 'string' && (o as any).indexName.length > 0;

try { return await tool.execute({ context, mastra, requestContext }); } catch (e) { if (e.message.startsWith('indexName is required')) { /* supply indexName and retry */ } else throw e; }

When it happens

Trigger: Running the tool without options.indexName and without requestContext.get('indexName'); passing indexName: '' ; RequestContext overrides returning empty strings.

Common situations: Configuring the tool with only vectorStore/index but forgetting indexName; setting indexName via requestContext in a path that doesn't propagate it; renaming an index but leaving the old config blank.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• vectorStoreName is required, got: ${vectorStoreName}
• indexName is required, got: ${indexName}
• VectorStoreResolver returned invalid value: expected MastraV
• Google RBAC roleMapping is required.
• Cookie password must be at least 32 characters. Set OKTA_COO

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