{"record":{"id":"e36fd43ab9c33837","repo":"mastra-ai/mastra","slug":"unknown-strategy-strategy","errorCode":null,"errorMessage":"Unknown strategy: ${strategy}","messagePattern":"Unknown strategy: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/document/document.ts","lineNumber":191,"sourceCode":"        character: options => this.chunkCharacter(options),\n        token: options => this.chunkToken(options),\n        markdown: options => this.chunkMarkdown(options),\n        html: options => this.chunkHTML(options),\n        json: options => this.chunkJSON(options),\n        latex: options => this.chunkLatex(options),\n        sentence: options => this.chunkSentence(options),\n        'semantic-markdown': options => this.chunkSemanticMarkdown(options),\n      };\n    }\n    return this._strategyMap;\n  }\n\n  private async chunkBy<K extends ChunkStrategy>(strategy: K, options?: StrategyOptions[K]): Promise<void> {\n    const chunkingFunc = this.strategyMap[strategy];\n    if (chunkingFunc) {\n      await chunkingFunc(options);\n    } else {\n      throw new Error(`Unknown strategy: ${strategy}`);\n    }\n  }\n\n  async chunkRecursive(options?: RecursiveChunkOptions): Promise<void> {\n    if (options?.language) {\n      const rt = RecursiveCharacterTransformer.fromLanguage(options.language, options);\n      const textSplit = rt.transformDocuments(this.chunks);\n      this.chunks = textSplit;\n      return;\n    }\n\n    const rt = new RecursiveCharacterTransformer(options);\n    const textSplit = rt.transformDocuments(this.chunks);\n    this.chunks = textSplit;\n  }\n\n  async chunkCharacter(options?: CharacterChunkOptions): Promise<void> {\n    const rt = new CharacterTransformer({","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/document/document.ts#L173-L209","documentation":"Document.chunkBy looks up a chunking function in the instance's strategyMap by strategy name and executes it. If the strategy key is not present in the map, there is no registered implementation for it, so the library throws this error rather than silently doing nothing. It is an internal dispatch guard — public callers normally go through chunk() with known strategy names.","triggerScenarios":"Calling chunkBy (directly or via Document.chunk with a strategy name) with a string not in strategyMap — e.g. a typo like 'sentence' vs the registered strategy, a custom strategy name never registered on the Document instance, or passing a strategy from an older API version that was renamed/removed.","commonSituations":"Typos in the strategy string, upgrading @mastra/rag where a strategy was renamed, or attempting to use a strategy (like HTML/JSON chunking) through the generic dispatch when it was expected to be registered differently.","solutions":["Check the exact strategy name against the Document's registered strategies (chunkRecursive, chunkSentence, chunkHTML, chunkJSON, etc.) and use the correct one.","Call the specific typed method directly (e.g. doc.chunkSentence({ maxSize: 512 })) instead of the generic dispatch.","If using a custom strategy, register it in strategyMap before calling chunkBy.","Verify @mastra/rag version to confirm the strategy exists in your installed version."],"exampleFix":"// before\nawait doc.chunk({ strategy: 'sentance', options: { maxSize: 512 } }); // typo\n\n// after\nawait doc.chunk({ strategy: 'sentence', options: { maxSize: 512 } });","handlingStrategy":"validation","validationCode":"const KNOWN = ['character', 'recursive', 'sentence', 'token', 'html', 'json'] as const;\nif (!KNOWN.includes(strategy as any)) throw new Error(`Unsupported strategy: ${strategy}`);","typeGuard":"type ChunkStrategy = 'character' | 'recursive' | 'sentence' | 'token' | 'html' | 'json';\nfunction isChunkStrategy(s: string): s is ChunkStrategy {\n  return ['character', 'recursive', 'sentence', 'token', 'html', 'json'].includes(s);\n}","tryCatchPattern":"try {\n  await doc.chunk({ strategy, options });\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Unknown strategy')) {\n    await doc.chunkRecursive(options); // safe default strategy\n  } else throw e;\n}","preventionTips":["Use the exported ChunkStrategy union type instead of raw strings.","Call typed methods (chunkSentence, chunkJSON, ...) directly to get compile-time checks.","Re-check strategy names after upgrading @mastra/rag."],"tags":["rag","chunking","invalid-argument","typescript"],"backgroundTag":"unknown-strategy","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}