mastra-ai/mastra · error · MastraError

IDs array length must match vectors array length

Error message

IDs array length must match vectors array length

What it means

Thrown by validateUpsertInput when the optional ids array length differs from the vectors array length. Every vector must have exactly one corresponding id (or none at all, letting the store generate ids).

Source

Thrown at packages/core/src/vector/validation.ts:54

  }

  // Validate metadata length matches vectors length (skip if metadata is empty/not provided)
  if (metadata && metadata.length > 0 && metadata.length !== vectors.length) {
    throw new MastraError({
      id: createVectorErrorId(storeName, 'UPSERT', 'METADATA_LENGTH_MISMATCH'),
      domain: ErrorDomain.MASTRA_VECTOR,
      category: ErrorCategory.USER,
      details: {
        message: 'Metadata array length must match vectors array length',
        vectorsLength: vectors.length,
        metadataLength: metadata.length,
      },
    });
  }

  // Validate ids length matches vectors length
  if (ids && ids.length !== vectors.length) {
    throw new MastraError({
      id: createVectorErrorId(storeName, 'UPSERT', 'IDS_LENGTH_MISMATCH'),
      domain: ErrorDomain.MASTRA_VECTOR,
      category: ErrorCategory.USER,
      details: {
        message: 'IDs array length must match vectors array length',
        vectorsLength: vectors.length,
        idsLength: ids.length,
      },
    });
  }
}

/**
 * Validates topK parameter for queries
 *
 * @param storeName - Name of the vector store (e.g., 'PG', 'CHROMA')
 * @param topK - Number of results to return
 * @throws MastraError if topK is not a positive integer

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure ids.length === vectors.length or omit ids entirely
2. Derive ids from the same source list as vectors so they stay in sync
3. Add an assertion at the call site comparing both lengths

Example fix

// before
await store.upsert({ indexName: 'docs', vectors, ids: ids.slice(0, 5) });
// after
const idList = vectors.map((_, i) => ids[i] ?? crypto.randomUUID());
await store.upsert({ indexName: 'docs', vectors, ids: idList });

if (ids && ids.length !== vectors.length) {
  throw new Error(`ids ${ids.length} != vectors ${vectors.length}`);
}

function idsMatch(vectors: unknown[], ids?: string[]): ids is string[] {
  return Array.isArray(ids) && ids.length === vectors.length;
}

try {
  await store.upsert({ indexName, vectors, ids });
} catch (e) {
  if (e instanceof MastraError && e.id.includes('IDS_LENGTH_MISMATCH')) {
    console.error('ids out of sync with vectors', e.details);
  }
  throw e;
}

When it happens

Trigger: Calling upsert with N vectors and M ids where N !== M; reusing a stale ids array after the vectors array changed length; omitting ids for some records while providing others.

Common situations: Merging batches from two sources where ids were deduplicated but vectors were not; regenerating embeddings after docs changed without regenerating ids.

Related errors

• Vectors array cannot be empty
• Metadata array length must match vectors array length
• Vector at index ${i} is null or undefined
• Vector contains invalid value (null, undefined, NaN, or Infi
• topK must be a positive integer

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