mastra-ai/mastra · error · HTTPException

Vector name is required

Error message

Vector name is required

What it means

HTTP 400 thrown by getVector in the vector handler: the vectorName path/query parameter is missing, so the server cannot even look up a vector store. No MastraVector lookup is attempted.

Source

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

}

interface CreateIndexRequest {
  indexName: string;
  dimension: number;
  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,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a vectorName matching a vector registered in your Mastra instance (e.g. GET /api/vectors/my-vector/query).
2. Check the client call site for an undefined/empty name variable before building the URL.
3. Update client SDK calls to the current route signature.

Example fix

// before
await fetch(`/api/vectors/${undefined}/query`)
// after
const vectorName = 'my-store';
await fetch(`/api/vectors/${encodeURIComponent(vectorName)}/query`)

if (!vectorName) throw new Error('vectorName is required before calling vector API');
const res = await fetch(`/api/vectors/${encodeURIComponent(vectorName)}/query`, {...});

function hasVectorName(name: string | undefined | null): name is string {
  return typeof name === 'string' && name.length > 0;
}

try {
  return await queryVector(vectorName, params);
} catch (e) {
  if (isHttpException(e, 400) && /Vector name is required/.test(e.message)) {
    throw new ConfigError('vectorName missing — check client call site');
  }
  throw e;
}

When it happens

Trigger: GET/POST to vector routes (query, upsert, etc.) without the vectorName parameter — e.g. GET /api/vectors or a client call with an undefined name.

Common situations: Client code building URLs with template literals where the variable is undefined/empty; renaming a vector config and leaving old client calls without a name; missing route params after API path changes.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Tool call id is required
• resourceId and threadId are required when runId is not provi
• threadId is required
• Run id is required
• Messages should be an array

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