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.

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)

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.

Related errors

• HTML chunking requires either headers or sections to be spec
• Sentence 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/769d346fc6bcddbd. Report an issue: GitHub.