mastra-ai/mastra · error

VectorStoreResolver returned invalid value: expected MastraV

Error message

VectorStoreResolver returned invalid value: expected MastraVector instance, got ${receivedType}${contextStr}

What it means

resolveVectorStore accepts either a MastraVector instance or a resolver; when the resolved value is neither (e.g. undefined because mastra.getVector(name) found no store, or a plain object/string), it throws this error reporting the received value's type and context. It guards against misconfigured vector store resolution inside tools.

Source

Thrown at packages/rag/src/utils/tool-helpers.ts:102

      // Validate that the resolver returned a valid MastraVector
      if (!isValidMastraVector(resolved)) {
        const contextStr = buildContextString(context);
        const receivedType = resolved === null ? 'null' : resolved === undefined ? 'undefined' : typeof resolved;

        if (fallbackOnInvalid) {
          logger?.warn(
            `VectorStoreResolver returned invalid value: expected MastraVector instance, got ${receivedType}${contextStr}. Falling back to mastra.getVector("${vectorStoreName}").`,
            { contextStr, receivedType },
          );
          // Fall back to mastra.getVector if available
          if (mastra && vectorStoreName) {
            return mastra.getVector(vectorStoreName);
          }
          return undefined;
        }

        throw new Error(
          `VectorStoreResolver returned invalid value: expected MastraVector instance, got ${receivedType}${contextStr}`,
        );
      }

      return resolved;
    }

    // Validate static vectorStore option
    if (!isValidMastraVector(vectorStoreOption)) {
      const contextStr = buildContextString(context);
      const receivedType =
        vectorStoreOption === null ? 'null' : vectorStoreOption === undefined ? 'undefined' : typeof vectorStoreOption;

      if (fallbackOnInvalid) {
        logger?.warn(
          `vectorStore option is not a valid MastraVector instance: got ${receivedType}${contextStr}. Falling back to mastra.getVector("${vectorStoreName}").`,
          { contextStr, receivedType },
        );

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the vector before use: mastra = new Mastra({ vectors: { 'my-store': vector } }) and use the same name in the tool
2. If using a custom resolver, make sure it returns a MastraVector instance (wrap raw clients: new MastraVector(client))
3. Log the registered vector names at startup and compare with vectorStoreName

Example fix

// before
resolveVector: () => pgClient, // raw client, not MastraVector
// after
resolveVector: () => new MastraVector(pgClient),

const vec = mastra.getVector('my-store');
if (!(vec instanceof MastraVector)) throw new Error('my-store is not registered as a MastraVector');

const isMastraVector = (v: unknown): v is MastraVector => v instanceof MastraVector;

try { return await tool.execute(ctx); } catch (e) { if (e.message.startsWith('VectorStoreResolver returned invalid value')) { /* re-register the vector, then retry */ } else throw e; }

When it happens

Trigger: mastra.getVector(vectorStoreName) returns undefined because no vector was registered under that name; a custom VectorStoreResolver callback returns null/undefined or the wrong object type.

Common situations: Typo in the registered vector name vs the one passed to the tool; vector registered on a different Mastra instance than the one executing the tool; custom resolver returning before registration completes or returning a non-MastraVector client (e.g. the raw store SDK client).

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

• `retrieval: { vector: true }` requires a vector store. Pass
• Subconscious semantic knowledge requires a vector store. Pas
• indexName is required, got: ${indexName}
• vectorStoreName is required, got: ${vectorStoreName}
• indexName is required, got: ${indexName}

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