vectorStore option is not a valid MastraVector instance: got

Error message

vectorStore option is not a valid MastraVector instance: got ${receivedType}${contextStr}

What it means

resolveVectorStore in @mastra/rag validates the `vectorStore` option passed to RAG tool helpers. The option must be an instance of MastraVector (or be resolvable via a Mastra instance + vectorStoreName). This error is thrown when the value provided has the wrong type — e.g. a plain object, class reference, or wrong library's client.

Source

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

    // 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 },
        );
        // Fall back to mastra.getVector if available
        if (mastra && vectorStoreName) {
          return mastra.getVector(vectorStoreName);
        }
        return undefined;
      }

      throw new Error(`vectorStore option is not a valid MastraVector instance: got ${receivedType}${contextStr}`);
    }

    return vectorStoreOption;
  }

  if (mastra) {
    return mastra.getVector(vectorStoreName);
  }

  return undefined;
}

/**
 * Coerces a topK value to a number, handling string inputs and providing a default.
 * Validates that the result is a finite positive number greater than zero.
 * @param topK - The value to coerce (number, string, or undefined)
 * @param defaultValue - Default value if coercion fails (defaults to 10)
 * @returns A valid positive number for topK, or defaultValue if invalid/non-finite/zero/negative

View on GitHub (pinned to 75dd419e61)

Solutions

Pass an actual MastraVector instance, e.g. `new PgVector({ connectionString })`, as the `vectorStore` option.
Alternatively pass `mastra` plus `vectorStoreName` so the helper resolves the store via `mastra.getVector(name)`.
Verify the instance comes from @mastra/core's MastraVector-compatible family, not a vendor SDK client.
Log `typeof vectorStore` / constructor name at the call site to confirm what is actually being passed.

Example fix

// before
const tool = createVectorQueryTool({ vectorStore: PgVector, indexName: 'docs' });
// after
const store = new PgVector({ connectionString: process.env.DATABASE_URL });
const tool = createVectorQueryTool({ vectorStore: store, indexName: 'docs' });

Defensive patterns

Strategy: type-guard

Validate before calling

function isMastraVector(v: unknown): boolean {
  return !!v && typeof v === 'object' && typeof (v as any).query === 'function' && typeof (v as any).upsert === 'function';
}
if (!isMastraVector(vectorStore)) throw new TypeError('vectorStore must be a MastraVector instance');

Type guard

function isMastraVector(v: unknown): v is MastraVector {
  return v instanceof Object && typeof (v as MastraVector).query === 'function';
}

Try / catch

try {
  const tool = createVectorQueryTool({ vectorStore, indexName });
} catch (e) {
  if ((e as Error).message.includes('not a valid MastraVector')) {
    throw new Error('Config error: construct the store, e.g. new PgVector({ connectionString })', { cause: e });
  }
  throw e;
}

Prevention

Always pass constructed instances, never classes or vendor SDK clients.
Prefer resolving stores by name via `mastra` + `vectorStoreName`.
Add a unit test that constructs each RAG tool with the real store instance.

When it happens

Trigger: Passing a non-MastraVector value as the `vectorStore` option (e.g. the vector store class itself instead of an instance, a raw Pinecone/pgvector client, or a deserialized plain object) while not supplying a `mastra` instance that can resolve it by name.

Common situations: Config mistakes after refactoring: passing `new PgVector` config args instead of the constructed instance, importing the wrong class, or reading the store from an old context object where it was serialized and lost its prototype.

Related errors

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