mastra-ai/mastra · error

indexName is required, got: ${indexName}

Error message

indexName is required, got: ${indexName}

What it means

createVectorQueryTool's execute resolves indexName from requestContext or options; when it is empty/undefined the tool throws this error with the received value. Without an index name the vector query has nothing to search.

Source

Thrown at packages/rag/src/tools/vector-query.ts:54

      // The `context` parameter from `createTool` is loosely typed and the
      // generated tool types don't always surface `tracingContext`. The cast
      // is intentional: when `context` or `tracingContext` is undefined,
      // `createObservabilityContext` falls back to `noOpTracingContext`, so
      // downstream span creation safely no-ops.
      const { requestContext, mastra, tracingContext } = (context as any) || {};
      const observabilityContext = createObservabilityContext(tracingContext);
      const indexName: string = requestContext?.get('indexName') ?? options.indexName;
      const vectorStoreName: string =
        'vectorStore' in options ? storeName : (requestContext?.get('vectorStoreName') ?? storeName);
      const includeVectors: boolean = requestContext?.get('includeVectors') ?? options.includeVectors ?? false;
      const includeSources: boolean = requestContext?.get('includeSources') ?? options.includeSources ?? true;
      const reranker: RerankConfig | undefined = requestContext?.get('reranker') ?? options.reranker;
      const databaseConfig = requestContext?.get('databaseConfig') ?? options.databaseConfig;
      const model: MastraEmbeddingModel<string> = requestContext?.get('model') ?? options.model;
      const providerOptions: ProviderOptions['providerOptions'] =
        requestContext?.get('providerOptions') ?? options.providerOptions;

      if (!indexName) throw new Error(`indexName is required, got: ${indexName}`);
      if (!vectorStoreName) throw new Error(`vectorStoreName is required, got: ${vectorStoreName}`); // won't fire

      const topK: number = requestContext?.get('topK') ?? (inputData.topK as number) ?? 10;
      const filter: unknown = requestContext?.get('filter') ?? inputData.filter;
      const queryText = inputData.queryText;
      const enableFilter = !!requestContext?.get('filter') || (options.enableFilter ?? false);

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

        const vectorStore = await resolveVectorStore(options, { requestContext, mastra, vectorStoreName });
        if (!vectorStore) {
          if (logger) {
            logger.error('Vector store not found', { vectorStore: vectorStoreName });

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass indexName explicitly: createVectorQueryTool({ vectorStore, indexName: 'my-index', model })
2. Ensure requestContext middleware sets 'indexName' when relying on per-request configuration
3. Confirm the index actually exists in the vector store under that exact name

Example fix

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

const indexName = requestContext?.get('indexName') ?? options.indexName;
if (!indexName) throw new Error('createVectorQueryTool: 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(ctx); } catch (e) { if (e.message.startsWith('indexName is required')) { /* set indexName and re-run */ } else throw e; }

When it happens

Trigger: Creating the tool without an indexName option and executing without requestContext.get('indexName'); passing indexName: '' or a variable that is undefined.

Common situations: Building the tool in a factory where indexName is injected later but used earlier; typo'd option key (idxName); server setups where RequestContext is expected to provide the index but doesn't.

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

• indexName is required, got: ${indexName}
• vectorStoreName is required, got: ${vectorStoreName}
• 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/7eeff765829ecb7f. Report an issue: GitHub.