{"record":{"id":"54b06cc972cafc86","repo":"mastra-ai/mastra","slug":"vectorstoreresolver-returned-invalid-value-expect","errorCode":null,"errorMessage":"VectorStoreResolver returned invalid value: expected MastraVector instance, got ${receivedType}${contextStr}","messagePattern":"VectorStoreResolver returned invalid value: expected MastraVector instance, got (.+?)(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/utils/tool-helpers.ts","lineNumber":102,"sourceCode":"\n      // Validate that the resolver returned a valid MastraVector\n      if (!isValidMastraVector(resolved)) {\n        const contextStr = buildContextString(context);\n        const receivedType = resolved === null ? 'null' : resolved === undefined ? 'undefined' : typeof resolved;\n\n        if (fallbackOnInvalid) {\n          logger?.warn(\n            `VectorStoreResolver returned invalid value: expected 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(\n          `VectorStoreResolver returned invalid value: expected MastraVector instance, got ${receivedType}${contextStr}`,\n        );\n      }\n\n      return resolved;\n    }\n\n    // 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        );","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/utils/tool-helpers.ts#L84-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Register the vector before use: mastra = new Mastra({ vectors: { 'my-store': vector } }) and use the same name in the tool","If using a custom resolver, make sure it returns a MastraVector instance (wrap raw clients: new MastraVector(client))","Log the registered vector names at startup and compare with vectorStoreName"],"exampleFix":"// before\nresolveVector: () => pgClient, // raw client, not MastraVector\n// after\nresolveVector: () => new MastraVector(pgClient),","handlingStrategy":"validation","validationCode":"const vec = mastra.getVector('my-store');\nif (!(vec instanceof MastraVector)) throw new Error('my-store is not registered as a MastraVector');","typeGuard":"const isMastraVector = (v: unknown): v is MastraVector => v instanceof MastraVector;","tryCatchPattern":"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; }","preventionTips":["Register vectors in the Mastra constructor ({ vectors: {...} }) before tool execution","Wrap raw store clients in new MastraVector(...) inside custom resolvers","Add an integration test that resolves every vectorStoreName used by tools at startup"],"tags":["configuration","validation","tool","vector-store"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}