mastra-ai/mastra · error · HTTPException

Invalid request index, indexName and positive dimension numb

Error message

Invalid request index, indexName and positive dimension number are required.

What it means

This HTTP 400 error is thrown by the createIndex server handler in packages/server/src/server/handlers/vector.ts when the request body fails basic validation. The Mastra server validates that an indexName is present (truthy) and that dimension is a positive number before delegating to the underlying vector store's createIndex. It exists to fail fast with a clear message instead of an opaque error deep inside the vector store adapter.

Source

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

    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) {
  try {
    if (!indexName || typeof dimension !== 'number' || dimension <= 0) {
      throw new HTTPException(400, {
        message: 'Invalid request index, indexName and positive dimension number are required.',
      });
    }

    if (metric && !['cosine', 'euclidean', 'dotproduct'].includes(metric)) {
      throw new HTTPException(400, { message: 'Invalid metric. Must be one of: cosine, euclidean, dotproduct' });
    }

    const vector = getVector(mastra, vectorName);
    await vector.createIndex({ indexName, dimension, metric });
    return { success: true };
  } catch (error) {
    return handleError(error, 'Error creating index');
  }
}

// Query vectors
export async function queryVectors({

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure the request body includes indexName as a non-empty string.
2. Send dimension as a JSON number (not a string) greater than 0, e.g. 1536.
3. If dimension comes from config/env, coerce with Number() and validate before sending.
4. Verify you are hitting the correct route with a JSON content-type body.

Example fix

// before
await fetch('/api/vectors/my-store/indexes', { method: 'POST', body: JSON.stringify({ dimension: '1536' }) });
// after
await fetch('/api/vectors/my-store/indexes', { method: 'POST', body: JSON.stringify({ indexName: 'my_index', dimension: 1536, metric: 'cosine' }) });

function assertCreateIndexRequest(body) {
  const { indexName, dimension } = body ?? {};
  if (typeof indexName !== 'string' || indexName.length === 0) throw new TypeError('indexName is required');
  if (typeof dimension !== 'number' || !Number.isFinite(dimension) || dimension <= 0) throw new TypeError('dimension must be a positive number');
  return body;
}

function isValidDimension(d) { return typeof d === 'number' && Number.isFinite(d) && Number.isInteger(d) && d > 0; }

try {
  await client.createIndex({ indexName, dimension });
} catch (e) {
  if (e.status === 400 && /Invalid request index/.test(e.message)) {
    console.error('createIndex payload rejected:', { indexName, dimension });
  }
  throw e;
}

When it happens

Trigger: POSTing to the create-index route with a body missing indexName, omitting dimension, sending dimension as a string (e.g. "1536"), sending dimension as 0 or a negative number, or sending a non-numeric value like null/NaN.

Common situations: Clients serializing query params instead of a JSON body; dimension taken from an untyped config/env var that comes through as a string; template-built requests where indexName is an empty string from an unset variable; copying an older API example where dimension was optional.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid metric. Must be one of: cosine, euclidean, dotproduc
• Invalid request query. indexName and queryVector array are r
• Index name is required
• 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/0017a4ee64e2d79f. Report an issue: GitHub.