Invalid parameters for ${strategy} strategy: '${keys}' not s

Error message

Invalid parameters for ${strategy} strategy: '${keys}' not supported

What it means

When the Zod schema for the chosen strategy rejects the params, validateChunkParams inspects the issues for an 'unrecognized_keys' code. If found, it throws this error naming exactly which keys are not supported for that strategy. It surfaces typos or options belonging to a different chunking strategy.

Source

Thrown at packages/rag/src/document/validation.ts:134

  'semantic-markdown': semanticMarkdownChunkOptionsSchema,
  latex: latexChunkOptionsSchema,
} as const;

export function validateChunkParams(strategy: ChunkStrategy, params: any): void {
  const schema = validationSchemas[strategy];
  if (!schema) {
    throw new Error(`Unknown chunking strategy: ${strategy}`);
  }

  const result = schema.safeParse(params);
  if (!result.success) {
    // Extract unrecognized keys for cleaner error message
    // Use 'issues' for Zod v4 compatibility (also available in Zod v3)
    const issues = result.error.issues;
    const unrecognizedError = issues.find((e: any) => e.code === 'unrecognized_keys');
    if (unrecognizedError && 'keys' in unrecognizedError) {
      const keys = (unrecognizedError as any).keys.join(', ');
      throw new Error(`Invalid parameters for ${strategy} strategy: '${keys}' not supported`);
    }

    // Fallback to general error message for other validation issues
    const errorMessage = issues
      .map((e: any) => `${e.path.length > 0 ? e.path.join('.') : 'parameter'}: ${e.message}`)
      .join(', ');

    throw new Error(`Invalid parameters for ${strategy} strategy: ${errorMessage}`);
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

Remove the keys listed in the error message; they are not part of this strategy's schema.
Move strategy-specific keys to the correct strategy (e.g. encodingName/modelName belong to token-based chunking).
Check the exported options type for the strategy to see the exact allowed keys.
If the key is genuinely needed, it means you want a different strategy — switch strategy rather than forcing the option.

Example fix

// before
await chunk(docs, { strategy: 'sentence', params: { maxSize: 500, overlap: 100, encodingName: 'cl100k_base' } });
// after
await chunk(docs, { strategy: 'sentence', params: { maxSize: 500, overlap: 100 } });

Defensive patterns

Strategy: validation

Validate before calling

const allowed = new Set(['maxSize','overlap','separator','separatorPosition','lengthFunction','addStartIndex','stripWhitespace']);
const extra = Object.keys(params).filter(k => !allowed.has(k));
if (extra.length) throw new Error(`Unsupported keys for this strategy: ${extra.join(', ')}`);

Try / catch

try {
  await chunk(docs, { strategy, params });
} catch (e) {
  if ((e as Error).message.includes('not supported')) {
    console.error('Remove or relocate the listed keys; they belong to another strategy');
  }
  throw e;
}

Prevention

Use strategy-specific typed option objects so excess keys are compile errors.
Don't share one params object across strategies; build per-strategy configs.
Keep tiktoken options (encodingName, modelName) only in token strategies.
Match mastra option names (maxSize/overlap), not other libraries' (chunkSize/chunkOverlap).

When it happens

Trigger: Passing options not in the strategy's schema, e.g. { strategy: 'character', params: { separator: '\n\n', encodingName: 'cl100k_base' } } — encodingName belongs to token chunking; or passing 'model'/'modelName' to character chunking; or misspelled keys like 'maxsize'.

Common situations: Reusing one params object for multiple strategies; mixing LangChain option names (chunkSize vs maxSize); adding tiktoken options to non-token strategies; IDE autocompleting from the wrong union member.

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

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