mastra-ai/mastra · error

Sentence chunking requires maxSize to be specified

Error message

Sentence chunking requires maxSize to be specified

What it means

chunkSentence uses SentenceTransformer, which requires maxSize to define the upper bound on sentence-chunk size (alongside optional minSize and targetSize). Without it the transformer cannot bound chunk sizes, so the library throws this validation error up front.

Source

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

    this.chunks = textSplit;
  }

  async chunkMarkdown(options?: MarkdownChunkOptions): Promise<void> {
    if (options?.headers) {
      const rt = new MarkdownHeaderTransformer(options.headers, options?.returnEachLine, options?.stripHeaders);
      const textSplit = rt.transformDocuments(this.chunks);
      this.chunks = textSplit;
      return;
    }

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

  async chunkSentence(options?: SentenceChunkOptions): Promise<void> {
    if (!options?.maxSize) {
      throw new Error('Sentence chunking requires maxSize to be specified');
    }

    const rt = new SentenceTransformer({
      minSize: options?.minSize,
      maxSize: options?.maxSize,
      targetSize: options?.targetSize,
      overlap: options?.overlap,
      sentenceEnders: options?.sentenceEnders,
      fallbackToWords: options?.fallbackToWords,
      fallbackToCharacters: options?.fallbackToCharacters,
      separatorPosition: options?.separatorPosition,
      lengthFunction: options?.lengthFunction,
      addStartIndex: options?.addStartIndex,
      stripWhitespace: options?.stripWhitespace,
    });

    const textSplit = rt.transformDocuments(this.chunks);
    this.chunks = textSplit;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass maxSize: doc.chunkSentence({ maxSize: 512 }).
2. Add sensible defaults when building options, e.g. { minSize: 50, maxSize: maxSize ?? 512, targetSize: targetSize ?? 256 }.
3. Validate the options object before calling the method.
4. Check the SentenceChunkOptions type for required vs optional fields.

Example fix

// before
await doc.chunkSentence({ targetSize: 200 }); // maxSize missing

// after
await doc.chunkSentence({ minSize: 50, maxSize: 512, targetSize: 200 });

if (typeof options?.maxSize !== 'number' || options.maxSize <= 0) {
  throw new Error('chunkSentence requires a positive maxSize');
}

function hasSentenceMaxSize(o: unknown): o is { maxSize: number } {
  return typeof (o as any)?.maxSize === 'number' && (o as any).maxSize > 0;
}

try {
  await doc.chunkSentence(options);
} catch (e) {
  if (e instanceof Error && e.message.includes('maxSize')) {
    await doc.chunkSentence({ ...options, maxSize: 512 });
  } else throw e;
}

When it happens

Trigger: Calling doc.chunkSentence() with no options, or with options lacking maxSize (e.g. chunkSentence({ targetSize: 200 })).

Common situations: Assuming sentence chunking works with defaults like other strategies, passing only minSize/targetSize, or constructing options dynamically where maxSize is optional in your config and undefined at runtime.

Related errors

• HTML chunking requires either headers or sections to be spec
• JSON chunking requires maxSize to be specified
• Chunk overlap (${overlap}) must be smaller than chunk size (
• Unknown chunking strategy: ${strategy}
• Invalid parameters for ${strategy} strategy: '${keys}' not s

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