{"record":{"id":"1a07ff8ec10022b5","repo":"mastra-ai/mastra","slug":"vectorstore-option-is-not-a-valid-mastravector-ins","errorCode":null,"errorMessage":"vectorStore option is not a valid MastraVector instance: got ${receivedType}${contextStr}","messagePattern":"vectorStore option is not a valid MastraVector instance: got (.+?)(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/utils/tool-helpers.ts","lineNumber":128,"sourceCode":"    // Validate static vectorStore option\n    if (!isValidMastraVector(vectorStoreOption)) {\n      const contextStr = buildContextString(context);\n      const receivedType =\n        vectorStoreOption === null ? 'null' : vectorStoreOption === undefined ? 'undefined' : typeof vectorStoreOption;\n\n      if (fallbackOnInvalid) {\n        logger?.warn(\n          `vectorStore option is not a valid MastraVector instance: got ${receivedType}${contextStr}. Falling back to mastra.getVector(\"${vectorStoreName}\").`,\n          { contextStr, receivedType },\n        );\n        // Fall back to mastra.getVector if available\n        if (mastra && vectorStoreName) {\n          return mastra.getVector(vectorStoreName);\n        }\n        return undefined;\n      }\n\n      throw new Error(`vectorStore option is not a valid MastraVector instance: got ${receivedType}${contextStr}`);\n    }\n\n    return vectorStoreOption;\n  }\n\n  if (mastra) {\n    return mastra.getVector(vectorStoreName);\n  }\n\n  return undefined;\n}\n\n/**\n * Coerces a topK value to a number, handling string inputs and providing a default.\n * Validates that the result is a finite positive number greater than zero.\n * @param topK - The value to coerce (number, string, or undefined)\n * @param defaultValue - Default value if coercion fails (defaults to 10)\n * @returns A valid positive number for topK, or defaultValue if invalid/non-finite/zero/negative","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/utils/tool-helpers.ts#L110-L146","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst tool = createVectorQueryTool({ vectorStore: PgVector, indexName: 'docs' });\n// after\nconst store = new PgVector({ connectionString: process.env.DATABASE_URL });\nconst tool = createVectorQueryTool({ vectorStore: store, indexName: 'docs' });","handlingStrategy":"type-guard","validationCode":"function isMastraVector(v: unknown): boolean {\n  return !!v && typeof v === 'object' && typeof (v as any).query === 'function' && typeof (v as any).upsert === 'function';\n}\nif (!isMastraVector(vectorStore)) throw new TypeError('vectorStore must be a MastraVector instance');","typeGuard":"function isMastraVector(v: unknown): v is MastraVector {\n  return v instanceof Object && typeof (v as MastraVector).query === 'function';\n}","tryCatchPattern":"try {\n  const tool = createVectorQueryTool({ vectorStore, indexName });\n} catch (e) {\n  if ((e as Error).message.includes('not a valid MastraVector')) {\n    throw new Error('Config error: construct the store, e.g. new PgVector({ connectionString })', { cause: e });\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["configuration","type-mismatch","rag"],"backgroundTag":"invalid-option-type","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}