mastra-ai/mastra · error

Keywords must be greater than 0

Error message

Keywords must be greater than 0

What it means

The KeywordExtractor constructor validates the keywords option: it must be at least 1 because extracting zero or negative keywords is meaningless and would break prompt construction / result slicing. The guard only fires when keywords is provided AND < 1; undefined falls back to the default of 5.

Source

Thrown at packages/rag/src/document/extractors/keywords.ts:34

};

/**
 * Extract keywords from a list of nodes.
 */
export class KeywordExtractor extends BaseExtractor {
  llm: MastraLanguageModel | MastraLegacyLanguageModel;
  keywords: number = 5;
  promptTemplate: KeywordExtractPrompt;

  /**
   * Constructor for the KeywordExtractor class.
   * @param {MastraLanguageModel} llm MastraLanguageModel instance.
   * @param {number} keywords Number of keywords to extract.
   * @param {string} [promptTemplate] Optional custom prompt template (must include {context})
   * @throws {Error} If keywords is less than 1.
   */
  constructor(options?: KeywordExtractArgs) {
    if (options?.keywords && options.keywords < 1) throw new Error('Keywords must be greater than 0');

    super();

    this.llm = options?.llm ?? baseLLM;
    this.keywords = options?.keywords ?? 5;
    this.promptTemplate = options?.promptTemplate
      ? new PromptTemplate({
          templateVars: ['context', 'maxKeywords'],
          template: options.promptTemplate,
        })
      : defaultKeywordExtractPrompt;
  }

  /**
   *
   * @param node Node to extract keywords from.
   * @returns Keywords extracted from the node.
   */

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a positive integer: new KeywordExtractor({ keywords: 5 }).
2. Omit the keywords option entirely to use the built-in default of 5.
3. Clamp/validate the value at the source: Math.max(1, config.keywords) or reject invalid config at load time.
4. If the count comes from user input, enforce a minimum of 1 in your form/config validation before constructing the extractor.

Example fix

// before
new KeywordExtractor({ keywords: config.keywordCount }); // may be 0

// after
new KeywordExtractor({ keywords: Math.max(1, config.keywordCount || 5) });

const keywords = options?.keywords;
if (keywords !== undefined && (!Number.isInteger(keywords) || keywords < 1)) {
  throw new Error('keywords must be a positive integer');
}

function isValidKeywordCount(n: unknown): n is number {
  return typeof n === 'number' && Number.isInteger(n) && n >= 1;
}

try {
  const extractor = new KeywordExtractor({ keywords });
} catch (e) {
  if (e instanceof Error && e.message.includes('Keywords must be greater than 0')) {
    extractor = new KeywordExtractor(); // default of 5
  } else throw e;
}

When it happens

Trigger: new KeywordExtractor({ keywords: 0 }) or keywords: -3 — typically the value is computed dynamically (e.g. from user input or a config value that is 0 by default) rather than hard-coded.

Common situations: Reading 'keyword count' from a UI or settings file where the default is 0, parsing a numeric option from a string that yields 0/NaN-adjacent values, or misconfigured template variables producing 0.

Related errors

• HTML chunking requires either headers or sections to be spec
• JSON chunking requires maxSize to be specified
• Sentence chunking requires maxSize to be specified
• Questions must be greater than 0
• Summaries must be one of 'self', 'prev', 'next'

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