mastra-ai/mastra · error · HTTPException

Invalid request index. indexName and vectors array are requi

Error message

Invalid request index. indexName and vectors array are required.

What it means

HTTP 400 thrown by upsertVectors: the request body must include indexName and a vectors array. If either is missing or vectors is not an array, the upsert is rejected before touching the vector store.

Source

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

  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.' });
    }

    const vector = getVector(mastra, vectorName);
    const result = await vector.upsert({ indexName, vectors, metadata, ids });
    return { ids: result };
  } catch (error) {
    return handleError(error, 'Error upserting vectors');
  }
}

// Create index
export async function createIndex({
  mastra,
  vectorName,
  indexName,
  dimension,
  metric,
}: Pick<VectorContext, 'mastra' | 'vectorName'> & CreateIndexRequest) {

View on GitHub (pinned to 75dd419e61)

Solutions

Send a JSON body with both indexName (string) and vectors (array of number[]).
Wrap a single embedding in an array: vectors: [embedding].
Validate the payload shape client-side before the request.

Example fix

// before
await client.upsert({ indexName: 'docs', vectors: embedding })
// after
await client.upsert({ indexName: 'docs', vectors: [embedding], metadata: [{ id: 'doc-1' }] })

Defensive patterns

Strategy: validation

Validate before calling

function assertUpsertBody(body: unknown): asserts body is { indexName: string; vectors: number[][] } {
  const b = body as any;
  if (!b || typeof b.indexName !== 'string' || !Array.isArray(b.vectors) || b.vectors.some(v => !Array.isArray(v))) {
    throw new Error('upsert requires indexName and vectors: number[][]');
  }
}

Type guard

function isValidUpsert(b: unknown): b is { indexName: string; vectors: number[][] } {
  const x = b as any;
  return !!x && typeof x.indexName === 'string' && Array.isArray(x.vectors) && x.vectors.every((v: unknown) => Array.isArray(v));
}

Try / catch

try {
  await upsert(body);
} catch (e) {
  if (isHttpException(e, 400) && e.message.includes('indexName and vectors array are required')) {
    throw new RequestShapeError('Wrap single embeddings in an array and include indexName');
  }
  throw e;
}

Prevention

Use the client SDK's typed upsert method instead of hand-rolled fetch calls.
Remember the API takes an array of embeddings, not a single vector.
Validate request bodies against the API schema in tests.

When it happens

Trigger: POST to the vector upsert route with body missing indexName, missing vectors, or vectors being an object/string instead of an array of embedding vectors.

Common situations: Client sending { indexName, vector: [...] } (singular key typo); passing a single vector instead of an array of vectors; JSON serialization dropping the array; forgetting the body entirely.

Related errors

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