mastra-ai/mastra · error · HTTPException

Index name is required

Error message

Index name is required

What it means

This HTTP 400 error is thrown by the describeIndex handler when indexName is missing or falsy (undefined, null, or empty string). describeIndex requires an explicit index to return its stats (dimension, count, metric), so the handler short-circuits with a clear message rather than attempting a store call. There is no 'describe all indexes' fallback on this route.

Source

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

  try {
    const vector = getVector(mastra, vectorName);

    const indexes = await vector.listIndexes();
    return indexes.filter(Boolean);
  } catch (error) {
    return handleError(error, 'Error listing indexes');
  }
}

// Describe index
export async function describeIndex({
  mastra,
  vectorName,
  indexName,
}: Pick<VectorContext, 'mastra' | 'vectorName'> & { indexName?: string }) {
  try {
    if (!indexName) {
      throw new HTTPException(400, { message: 'Index name is required' });
    }

    const vector = getVector(mastra, vectorName);
    const stats: IndexStats = await vector.describeIndex({ indexName });

    return {
      dimension: stats.dimension,
      count: stats.count,
      metric: stats.metric?.toLowerCase(),
    };
  } catch (error) {
    return handleError(error, 'Error describing index');
  }
}

// Delete index
export async function deleteIndex({
  mastra,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Always pass a non-empty indexName string to the describe-index request.
2. Log/inspect the value of indexName before the call to catch empty-string cases.
3. If you need store-level info, use the store stats route/handler instead of describeIndex.
4. Check for renamed fields after SDK/API upgrades.

Example fix

// before
const stats = await describeIndex({ mastra, vectorName: 'pg', indexName: selectedName ?? '' });
// after
if (!selectedName) return null;
const stats = await describeIndex({ mastra, vectorName: 'pg', indexName: selectedName });

function canDescribe(indexName) { return typeof indexName === 'string' && indexName.trim().length > 0; }
if (!canDescribe(selectedIndex)) return null;
const stats = await client.describeIndex({ indexName: selectedIndex });

function hasIndexName(v) { return typeof v === 'string' && v.length > 0; }

try {
  return await client.describeIndex({ indexName });
} catch (e) {
  if (e.status === 400 && /Index name is required/.test(e.message)) {
    return null; // no index selected yet
  }
  throw e;
}

When it happens

Trigger: Calling the describe-index route with indexName omitted from the body/query; passing an empty string after a failed lookup or unset variable; passing null from a caller that expected stats for the whole store.

Common situations: UI code building the request before the user selects an index; refactors that renamed indexName to name and left the old field undefined; dynamic index names interpolated from config that resolve to ''.

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

• Invalid request index, indexName and positive dimension numb
• Invalid metric. Must be one of: cosine, euclidean, dotproduc
• Invalid request query. indexName and queryVector array are r
• Agent ID is required
• Could not derive scorer definition ID from name. Please prov

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