Chunk overlap (${overlap}) must be smaller than chunk size (

Error message

Chunk overlap (${overlap}) must be smaller than chunk size (${maxSize}).

What it means

TextTransformer's constructor validates that the overlap between adjacent chunks is strictly smaller than the maximum chunk size. If overlap >= maxSize, chunking is impossible (chunks could never advance), so the constructor refuses to build an invalid transformer. This is a fail-fast configuration check.

Source

Thrown at packages/rag/src/document/transformers/text.ts:24

export abstract class TextTransformer implements Transformer {
  protected maxSize: number;
  protected overlap: number;
  protected lengthFunction: (text: string) => number;
  protected separatorPosition?: 'start' | 'end';
  protected addStartIndex: boolean;
  protected stripWhitespace: boolean;

  constructor({
    maxSize = 4000,
    overlap = 200,
    lengthFunction = (text: string) => text.length,
    separatorPosition,
    addStartIndex = false,
    stripWhitespace = true,
  }: BaseChunkOptions) {
    if (overlap >= maxSize) {
      throw new Error(`Chunk overlap (${overlap}) must be smaller than chunk size (${maxSize}).`);
    }
    this.maxSize = maxSize;
    this.overlap = overlap;
    this.lengthFunction = lengthFunction;
    this.separatorPosition = separatorPosition;
    this.addStartIndex = addStartIndex;
    this.stripWhitespace = stripWhitespace;
  }

  setAddStartIndex(value: boolean): void {
    this.addStartIndex = value;
  }

  abstract splitText({ text }: { text: string }): string[];

  createDocuments(texts: string[], metadatas?: Record<string, any>[]): Document[] {
    const _metadatas = metadatas || Array(texts.length).fill({});
    const documents: Document[] = [];

View on GitHub (pinned to 75dd419e61)

Solutions

Set overlap strictly less than maxSize, e.g. maxSize: 1000, overlap: 200.
Check that you are not passing a fraction (0.1–0.5) as overlap; convert it to an absolute number of characters/tokens first.
Verify a custom lengthFunction isn't inflating measured sizes; the comparison uses raw numeric values, but downstream chunking uses the function.

Example fix

// before
new TextTransformer({ maxSize: 512, overlap: 512 });
// after
new TextTransformer({ maxSize: 512, overlap: 128 });

Defensive patterns

Strategy: validation

Validate before calling

const maxSize = 512, overlap = 128;
if (overlap >= maxSize) throw new Error(`overlap (${overlap}) must be < maxSize (${maxSize})`);

Type guard

function isValidChunkConfig(o: { maxSize: number; overlap: number }): boolean {
  return Number.isInteger(o.maxSize) && o.maxSize > 0 && o.overlap >= 0 && o.overlap < o.maxSize;
}

Try / catch

try {
  const splitter = new TextTransformer({ maxSize: 512, overlap: 128 });
} catch (e) {
  if ((e as Error).message.includes('must be smaller than chunk size')) {
    console.error('Fix chunk config: overlap must be < maxSize');
  }
  throw e;
}

Prevention

Always set overlap to a fraction of maxSize (e.g. 10–20%) as an absolute number, never a ratio.
Never set overlap equal to maxSize; the check is strict (>).
Centralize chunking config in one typed constant/object so ratios can't leak in.
When switching length functions (chars vs tokens), recheck both maxSize and overlap scales.

When it happens

Trigger: new TextTransformer({ maxSize: 500, overlap: 500 }) or any call where the overlap option is greater than or equal to maxSize. Note the default maxSize is typically smaller than a passed overlap too, e.g. maxSize left at default while overlap is set high.

Common situations: Copy-pasting chunk configs from another library where overlap was expressed as a ratio (e.g. 0.2) and not noticing the default maxSize is small; switching from characters to tokens without rescaling sizes; off-by-one using overlap equal to size thinking it means contiguous chunks.

Related errors

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