mastra-ai/mastra · error · MastraError

Vector at index ${i} is null or undefined

Error message

Vector at index ${i} is null or undefined

What it means

validateVectorValues iterates the vectors array and throws if any element is null or undefined (a missing vector slot). A sparse or partially-filled number[][] cannot be embedded, so upsert fails fast with the offending index.

Source

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

        topK,
      },
    });
  }
}

/**
 * Validates vector components for NaN/Infinity values
 *
 * @param storeName - Name of the vector store (e.g., 'PG', 'CHROMA')
 * @param vectors - Array of vectors to validate
 * @throws MastraError if any vector contains NaN, Infinity, null, or undefined
 */
export function validateVectorValues(storeName: string, vectors: number[][]): void {
  for (let i = 0; i < vectors.length; i++) {
    const vector = vectors[i];

    if (!vector) {
      throw new MastraError({
        id: createVectorErrorId(storeName, 'UPSERT', 'INVALID_VECTOR'),
        domain: ErrorDomain.MASTRA_VECTOR,
        category: ErrorCategory.USER,
        details: {
          message: `Vector at index ${i} is null or undefined`,
          vectorIndex: i,
        },
      });
    }

    for (let j = 0; j < vector.length; j++) {
      const value = vector[j];

      if (value === null || value === undefined || !Number.isFinite(value)) {
        throw new MastraError({
          id: createVectorErrorId(storeName, 'UPSERT', 'INVALID_VECTOR_VALUE'),
          domain: ErrorDomain.MASTRA_VECTOR,
          category: ErrorCategory.USER,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Filter out null/undefined entries and their associated metadata/ids before upsert
2. Find the producer that left the hole and fix or retry failed embeddings
3. Assert every element is an array before calling upsert

Example fix

// before
await store.upsert({ indexName: 'docs', vectors: embeddingResults });
// after
const valid = vectors.filter((v): v is number[] => Array.isArray(v));
await store.upsert({ indexName: 'docs', vectors: valid });

const hole = vectors.findIndex((v) => v == null);
if (hole !== -1) throw new Error(`null vector at index ${hole}`);

function allVectorsPresent(v: unknown[]): v is number[][] {
  return v.every((x): x is number[] => Array.isArray(x));
}

try {
  await store.upsert({ indexName, vectors });
} catch (e) {
  if (e instanceof MastraError && e.id.includes('INVALID_VECTOR')) {
    console.error(`Bad vector at index ${e.details.vectorIndex}`);
  }
  throw e;
}

When it happens

Trigger: Passing an array like [[0.1, 0.2], , [0.3]] (holes), or an array built with fixed length where some slots were never assigned, or null entries from a failed embedding per-document.

Common situations: Batch embedding where some items failed and were replaced with null placeholders; Array(n) used to preallocate without filling.

Related errors

• Vectors array cannot be empty
• Metadata array length must match vectors array length
• IDs array length must match vectors array length
• Vector contains invalid value (null, undefined, NaN, or Infi
• Factory rules must be an object.

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