{"record":{"id":"e2a66b540f68e403","repo":"mastra-ai/mastra","slug":"unknown-chunking-strategy-strategy","errorCode":null,"errorMessage":"Unknown chunking strategy: ${strategy}","messagePattern":"Unknown chunking strategy: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/document/validation.ts","lineNumber":123,"sourceCode":"const latexChunkOptionsSchema = baseChunkOptionsSchema.strict();\n\n// Strategy-specific validation schemas\nconst validationSchemas = {\n  character: characterChunkOptionsSchema,\n  recursive: recursiveChunkOptionsSchema,\n  sentence: sentenceChunkOptionsSchema,\n  token: tokenChunkOptionsSchema,\n  json: jsonChunkOptionsSchema,\n  html: htmlChunkOptionsSchema,\n  markdown: markdownChunkOptionsSchema,\n  'semantic-markdown': semanticMarkdownChunkOptionsSchema,\n  latex: latexChunkOptionsSchema,\n} as const;\n\nexport function validateChunkParams(strategy: ChunkStrategy, params: any): void {\n  const schema = validationSchemas[strategy];\n  if (!schema) {\n    throw new Error(`Unknown chunking strategy: ${strategy}`);\n  }\n\n  const result = schema.safeParse(params);\n  if (!result.success) {\n    // Extract unrecognized keys for cleaner error message\n    // Use 'issues' for Zod v4 compatibility (also available in Zod v3)\n    const issues = result.error.issues;\n    const unrecognizedError = issues.find((e: any) => e.code === 'unrecognized_keys');\n    if (unrecognizedError && 'keys' in unrecognizedError) {\n      const keys = (unrecognizedError as any).keys.join(', ');\n      throw new Error(`Invalid parameters for ${strategy} strategy: '${keys}' not supported`);\n    }\n\n    // Fallback to general error message for other validation issues\n    const errorMessage = issues\n      .map((e: any) => `${e.path.length > 0 ? e.path.join('.') : 'parameter'}: ${e.message}`)\n      .join(', ');\n","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/document/validation.ts#L105-L141","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nawait chunk(docs, { strategy: 'recursive', ... });\n// after\nawait chunk(docs, { strategy: 'character', maxSize: 1000, overlap: 200 });","handlingStrategy":"validation","validationCode":"const VALID_STRATEGIES = ['character','sentence','token','semantic','semantic-markdown','html','markdown','json','latex'] as const;\nfunction assertValidStrategy(s: string): asserts s is typeof VALID_STRATEGIES[number] {\n  if (!VALID_STRATEGIES.includes(s as any)) throw new Error(`Unknown chunking strategy: ${s}`);\n}","typeGuard":"type ChunkStrategy = 'character'|'sentence'|'token'|'semantic'|'semantic-markdown'|'html'|'markdown'|'json'|'latex';\nfunction isChunkStrategy(s: string): s is ChunkStrategy {\n  return ['character','sentence','token','semantic','semantic-markdown','html','markdown','json','latex'].includes(s);\n}","tryCatchPattern":"try {\n  await chunk(docs, { strategy, ...rest });\n} catch (e) {\n  if ((e as Error).message.startsWith('Unknown chunking strategy')) {\n    console.error(`\"${strategy}\" is not registered; see ChunkStrategy type for valid values`);\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["rag","chunking","validation","configuration"],"backgroundTag":"invalid-chunking-strategy","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}