mastra-ai/mastra · error · Error

Semantic recall requires a vector store to be configured. h

Error message

Semantic recall requires a vector store to be configured.

https://mastra.ai/en/docs/memory/semantic-recall

What it means

Memory's constructor throws when threadConfig.semanticRecall is enabled but no vector store (config.vector) was provided. Semantic recall retrieves relevant past messages via vector similarity, which is impossible without an embedding/vector backend, so Mastra fails fast with a docs link.

Source

Thrown at packages/core/src/memory/memory.ts:172

  })

Or pass memory directly to processor arrays:
  new Agent({
    inputProcessors: [memory],
    outputProcessors: [memory]
  })

See: https://mastra.ai/en/docs/memory/processors`,
      );
    }
    if (config.storage) {
      this._storage = augmentWithInit(config.storage);
      this._hasOwnStorage = true;
    }

    if (this.threadConfig.semanticRecall) {
      if (!config.vector) {
        throw new Error(
          `Semantic recall requires a vector store to be configured.

https://mastra.ai/en/docs/memory/semantic-recall`,
        );
      }
      this.vector = config.vector;

      if (!config.embedder) {
        throw new Error(
          `Semantic recall requires an embedder to be configured.

https://mastra.ai/en/docs/memory/semantic-recall`,
        );
      }

      // Convert string embedder to ModelRouterEmbeddingModel
      if (typeof config.embedder === 'string') {
        this.embedder = new ModelRouterEmbeddingModel(config.embedder);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a vector store instance: new Memory({ storage, vector: new MastraVector(...) }) alongside the semanticRecall option.
2. If semantic recall is not needed, remove the semanticRecall option from the memory/thread config.
3. Gate the semanticRecall option on vector-store availability in environment-dependent configs.
4. Configure the vector index/embeddings per the docs at mastra.ai/en/docs/memory/semantic-recall.

Example fix

// before
new Memory({ storage, options: { semanticRecall: { topK: 5 } } }); // throws: no vector
// after
new Memory({
  storage,
  vector: new MastraVector(new PgVector(process.env.DATABASE_URL)),
  options: { semanticRecall: { topK: 5 } },
});

function assertSemanticRecallConfig(config) {
  const semanticRecall = config.options?.semanticRecall;
  if (semanticRecall && !config.vector) {
    throw new Error('semanticRecall is enabled but no vector store was passed (config.vector)');
  }
}

function hasVectorForSemanticRecall(config: MemoryConfig): config is MemoryConfig & { vector: MastraVector } {
  return !config.options?.semanticRecall || Boolean(config.vector);
}

try {
  const memory = new Memory(config);
} catch (e) {
  if (e instanceof Error && e.message.includes('Semantic recall requires a vector store')) {
    console.warn('semanticRecall disabled: no vector store configured');
    const memory = new Memory({ ...config, options: { ...config.options, semanticRecall: false } });
  } else throw e;
}

When it happens

Trigger: new Memory({ storage, options: { semanticRecall: true } }) — or semanticRecall: { topK, messageRange } — without passing a vector store instance as config.vector.

Common situations: Enabling semantic recall in options after initially configuring memory without a vector store; setting semanticRecall true via shared config that some deployments build without a vector; forgetting that semanticRecall in thread config implies a mandatory vector dependency.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• AGENT_NETWORK_MEMORY_REQUIRED
• Semantic recall requires an embedder to be configured. http
• Memory requires a storage provider to function. Add a storag
• Tried to create embedding index but no vector db is attached
• SEMANTIC_RECALL_MISSING_STORAGE_ADAPTER

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