What causes "Vector store ${vectorName} not found" in mastra-ai/mastra?

Register the vector store on the Mastra instance: new Mastra({ vectors: { 'my-store': new PgVector(...) } }).

mastra-ai/mastra · error · HTTPException

Vector store ${vectorName} not found

Error message

Vector store ${vectorName} not found

What it means

HTTP 404 thrown by getVector: a vectorName was provided but mastra.getVector(vectorName) returned undefined — no vector store with that name is registered on the Mastra instance.

Source

Thrown at packages/server/src/server/handlers/vector.ts:56

  metric?: 'cosine' | 'euclidean' | 'dotproduct';
}

interface QueryRequest {
  indexName: string;
  queryVector: number[];
  topK?: number;
  filter?: Record<string, any>;
  includeVector?: boolean;
}

function getVector(mastra: Context['mastra'], vectorName?: string): MastraVector {
  if (!vectorName) {
    throw new HTTPException(400, { message: 'Vector name is required' });
  }

  const vector = mastra.getVector(vectorName);
  if (!vector) {
    throw new HTTPException(404, { message: `Vector store ${vectorName} not found` });
  }

  return vector;
}

// Upsert vectors
export async function upsertVectors({
  mastra,
  vectorName,
  indexName,
  vectors,
  metadata,
  ids,
}: VectorContext & UpsertRequest) {
  try {
    if (!indexName || !vectors || !Array.isArray(vectors)) {
      throw new HTTPException(400, { message: 'Invalid request index. indexName and vectors array are required.' });
    }

View on GitHub (pinned to 75dd419e61)

Solutions

Register the vector store on the Mastra instance: new Mastra({ vectors: { 'my-store': new PgVector(...) } }).
Fix the vectorName to match the registered key exactly (check casing/spelling).
Verify the target server/environment has the vector plugin/config deployed.

Example fix

// before
const mastra = new Mastra({ agents: { ... } }); // no vectors
// after
const mastra = new Mastra({ agents: { ... }, vectors: { 'my-store': new PgVector(process.env.DATABASE_URL) } });

Defensive patterns

Strategy: try-catch

Validate before calling

const res = await fetch('/api/vectors').then(r => r.json());
const names = res.map(v => v.name);
if (!names.includes(vectorName)) throw new Error(`Vector '${vectorName}' not registered. Available: ${names.join(', ')}`);

Try / catch

try {
  return await vectorQuery(vectorName, params);
} catch (e) {
  if (isHttpException(e, 404) && e.message.includes('not found')) {
    console.error(`Vector store '${vectorName}' not registered on this Mastra instance. Check mastra config vectors map.`);
  }
  throw e;
}

Prevention

Keep vector registration keys in a shared constant used by both server config and clients.
Verify deployed environments register the same vectors as local dev.
List available vectors via the API before querying when debugging.

When it happens

Trigger: Any vector route call with a vectorName not present in the server's Mastra configuration (typo, vector not registered, wrong server/environment).

Common situations: Local dev registered the vector but the deployed instance did not; renamed the vector in mastra config without updating clients; casing mismatches; environment variable gates skipping vector registration.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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