mastra-ai/mastra · error · MastraError

topK must be a positive integer

Error message

topK must be a positive integer

What it means

validateTopK rejects any topK that is not a positive integer. topK is the number of nearest neighbors a query() should return, so 0, negatives, floats, NaN, or non-numbers are all invalid.

Source

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

      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
 */
export function validateTopK(storeName: string, topK: number): void {
  if (!Number.isInteger(topK) || topK <= 0) {
    throw new MastraError({
      id: createVectorErrorId(storeName, 'QUERY', 'INVALID_TOP_K'),
      domain: ErrorDomain.MASTRA_VECTOR,
      category: ErrorCategory.USER,
      details: {
        message: 'topK must be a positive integer',
        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
 */

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a positive integer, e.g. topK: 10
2. Clamp/round user input: topK = Math.max(1, Math.floor(Number(input) || 10))
3. Validate the value before calling query instead of relying on the store to throw

Example fix

// before
const results = await store.query({ indexName: 'docs', queryVector, topK: Number(req.query.limit) });
// after
const topK = Math.max(1, Math.floor(Number(req.query.limit) || 10));
const results = await store.query({ indexName: 'docs', queryVector, topK });

const topK = Math.max(1, Math.floor(Number(rawTopK)));
if (!Number.isInteger(topK) || topK <= 0) throw new Error('topK must be a positive integer');

function isValidTopK(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v > 0;
}

try {
  return await store.query({ indexName, queryVector, topK });
} catch (e) {
  if (e instanceof MastraError && e.id.includes('INVALID_TOP_K')) {
    return store.query({ indexName, queryVector, topK: 10 });
  }
  throw e;
}

When it happens

Trigger: Calling query({ indexName, queryVector, topK: 0 }), topK from parseInt of a bad string producing NaN, a float like 2.5, or a negative limit computed from pagination math.

Common situations: User-supplied limit passed through unvalidated; pagination page*size arithmetic going negative; config value loaded from env as a string then coerced incorrectly.

Understand the failure class

Background: "must be positive", "Invalid value": how libraries reject invalid parameter values (ValueError, ArgumentError, INVALID_PARAMETER_VALUE) — this error's family across 28 libraries.

Related errors

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

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