mastra-ai/mastra · error

Unknown strategy: ${strategy}

Error message

Unknown strategy: ${strategy}

What it means

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.

Source

Thrown at packages/rag/src/document/document.ts:191

        character: options => this.chunkCharacter(options),
        token: options => this.chunkToken(options),
        markdown: options => this.chunkMarkdown(options),
        html: options => this.chunkHTML(options),
        json: options => this.chunkJSON(options),
        latex: options => this.chunkLatex(options),
        sentence: options => this.chunkSentence(options),
        'semantic-markdown': options => this.chunkSemanticMarkdown(options),
      };
    }
    return this._strategyMap;
  }

  private async chunkBy<K extends ChunkStrategy>(strategy: K, options?: StrategyOptions[K]): Promise<void> {
    const chunkingFunc = this.strategyMap[strategy];
    if (chunkingFunc) {
      await chunkingFunc(options);
    } else {
      throw new Error(`Unknown strategy: ${strategy}`);
    }
  }

  async chunkRecursive(options?: RecursiveChunkOptions): Promise<void> {
    if (options?.language) {
      const rt = RecursiveCharacterTransformer.fromLanguage(options.language, options);
      const textSplit = rt.transformDocuments(this.chunks);
      this.chunks = textSplit;
      return;
    }

    const rt = new RecursiveCharacterTransformer(options);
    const textSplit = rt.transformDocuments(this.chunks);
    this.chunks = textSplit;
  }

  async chunkCharacter(options?: CharacterChunkOptions): Promise<void> {
    const rt = new CharacterTransformer({

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Check the exact strategy name against the Document's registered strategies (chunkRecursive, chunkSentence, chunkHTML, chunkJSON, etc.) and use the correct one.
  2. Call the specific typed method directly (e.g. doc.chunkSentence({ maxSize: 512 })) instead of the generic dispatch.
  3. If using a custom strategy, register it in strategyMap before calling chunkBy.
  4. Verify @mastra/rag version to confirm the strategy exists in your installed version.

Example fix

// before
await doc.chunk({ strategy: 'sentance', options: { maxSize: 512 } }); // typo

// after
await doc.chunk({ strategy: 'sentence', options: { maxSize: 512 } });
Defensive patterns

Strategy: validation

Validate before calling

const KNOWN = ['character', 'recursive', 'sentence', 'token', 'html', 'json'] as const;
if (!KNOWN.includes(strategy as any)) throw new Error(`Unsupported strategy: ${strategy}`);

Type guard

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

Try / catch

try {
  await doc.chunk({ strategy, options });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unknown strategy')) {
    await doc.chunkRecursive(options); // safe default strategy
  } else throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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