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.

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.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• Chunk overlap ( ) must be smaller than chunk size ( ).
• HTML chunking requires either headers or sections to be…
• Invalid parameters for
• Invalid parameters for
• JSON chunking requires maxSize to be specified

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

Appendix: 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)