What causes "Unknown chunking strategy: ${strategy}" in mastra-ai/mastra?

Use one of the registered strategies exactly: check the ChunkStrategy type/union exported by @mastra/rag (e.g. 'character', 'sentence', 'token', 'semantic', 'semantic-markdown', 'html', 'markdown', 'json', 'latex' as applicable to your version).

mastra-ai/mastra · error

Unknown chunking strategy: ${strategy}

Error message

Unknown chunking strategy: ${strategy}

What it means

validateChunkParams looks up a Zod schema for the requested ChunkStrategy in a fixed registry (character, sentence, semantic-markdown, latex, etc.). If the strategy string is not a key of that registry, there is no schema to validate against and the function throws immediately. It catches invalid strategy names before any chunking runs.

Source

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

const latexChunkOptionsSchema = baseChunkOptionsSchema.strict();

// Strategy-specific validation schemas
const validationSchemas = {
  character: characterChunkOptionsSchema,
  recursive: recursiveChunkOptionsSchema,
  sentence: sentenceChunkOptionsSchema,
  token: tokenChunkOptionsSchema,
  json: jsonChunkOptionsSchema,
  html: htmlChunkOptionsSchema,
  markdown: markdownChunkOptionsSchema,
  '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(', ');

View on GitHub (pinned to 75dd419e61)

Solutions

Use one of the registered strategies exactly: check the ChunkStrategy type/union exported by @mastra/rag (e.g. 'character', 'sentence', 'token', 'semantic', 'semantic-markdown', 'html', 'markdown', 'json', 'latex' as applicable to your version).
Fix the typo in the strategy string.
Upgrade or downgrade @mastra/rag if the strategy you need exists only in another version.
Validate user-supplied strategy strings against the exported strategy union before calling chunk.

Example fix

// before
await chunk(docs, { strategy: 'recursive', ... });
// after
await chunk(docs, { strategy: 'character', maxSize: 1000, overlap: 200 });

Defensive patterns

Strategy: validation

Validate before calling

const VALID_STRATEGIES = ['character','sentence','token','semantic','semantic-markdown','html','markdown','json','latex'] as const;
function assertValidStrategy(s: string): asserts s is typeof VALID_STRATEGIES[number] {
  if (!VALID_STRATEGIES.includes(s as any)) throw new Error(`Unknown chunking strategy: ${s}`);
}

Type guard

type ChunkStrategy = 'character'|'sentence'|'token'|'semantic'|'semantic-markdown'|'html'|'markdown'|'json'|'latex';
function isChunkStrategy(s: string): s is ChunkStrategy {
  return ['character','sentence','token','semantic','semantic-markdown','html','markdown','json','latex'].includes(s);
}

Try / catch

try {
  await chunk(docs, { strategy, ...rest });
} catch (e) {
  if ((e as Error).message.startsWith('Unknown chunking strategy')) {
    console.error(`"${strategy}" is not registered; see ChunkStrategy type for valid values`);
  }
  throw e;
}

Prevention

Let TypeScript infer the strategy from the union type instead of using plain strings.
Never pass user input directly as strategy without checking against the union.
When migrating from other libraries, map their splitter names to mastra strategies explicitly.
Re-check strategy names after upgrading @mastra/rag.

When it happens

Trigger: Calling chunk({ strategy: 'word' }) or any misspelled/unsupported strategy string, e.g. 'token' when only 'token'-style transformers exist under a different name, or 'recursive' which this library doesn't register.

Common situations: Migrating from LangChain's RecursiveCharacterTextSplitter and reusing the string 'recursive'; typos like 'semanticmarkdown'; dynamically building strategy names from user input; version changes where a strategy was renamed or removed.

Related errors

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