mastra-ai/mastra · error

JSON chunking requires maxSize to be specified

Error message

JSON chunking requires maxSize to be specified

What it means

chunkJSON uses RecursiveJsonTransformer, which needs a maxSize to know the maximum size a JSON chunk may reach before being split further. Without maxSize the transformer has no split criterion, so the library throws this validation error before doing any work.

Solutions

1. Provide maxSize in the options: doc.chunkJSON({ maxSize: 1024 }).
2. Ensure the value is defined and non-zero if sourced from configuration (add a default, e.g. maxSize ?? 1024).
3. Validate your options object before calling chunkJSON.
4. Review the JsonChunkOptions type to see which fields are required.

Example fix

// before
await doc.chunkJSON({ minSize: 100 }); // maxSize missing

// after
await doc.chunkJSON({ maxSize: 1024, minSize: 100 });

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

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

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

When it happens

Trigger: Calling doc.chunkJSON() or chunkJSON({}) / chunkJSON({ minSize: 100 }) where options.maxSize is undefined or 0/falsy.

Common situations: Omitting options entirely because other chunk strategies allow it, spreading a partial config object where maxSize was never set, or reading maxSize from config/env that is 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
• Sentence chunking requires maxSize to be specified

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

Appendix: source

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

          maxSize: options.maxSize,
          overlap: options.overlap,
          separatorPosition: options.separatorPosition,
          addStartIndex: options.addStartIndex,
          stripWhitespace: options.stripWhitespace,
        });
        textSplit = textSplitter.splitDocuments(textSplit);
      }

      this.chunks = textSplit;
      return;
    }

    throw new Error('HTML chunking requires either headers or sections to be specified');
  }

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

    const rt = new RecursiveJsonTransformer({
      maxSize: options?.maxSize,
      minSize: options?.minSize,
    });

    const textSplit = rt.transformDocuments({
      documents: this.chunks,
      ensureAscii: options?.ensureAscii,
      convertLists: options?.convertLists,
    });

    this.chunks = textSplit;
  }

  async chunkLatex(options?: LatexChunkOptions): Promise<void> {
    const rt = new LatexTransformer(options);

View on GitHub (pinned to 75dd419e61)