{"record":{"id":"769d346fc6bcddbd","repo":"mastra-ai/mastra","slug":"json-chunking-requires-maxsize-to-be-specified","errorCode":null,"errorMessage":"JSON chunking requires maxSize to be specified","messagePattern":"JSON chunking requires maxSize to be specified","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/document/document.ts","lineNumber":266,"sourceCode":"          maxSize: options.maxSize,\n          overlap: options.overlap,\n          separatorPosition: options.separatorPosition,\n          addStartIndex: options.addStartIndex,\n          stripWhitespace: options.stripWhitespace,\n        });\n        textSplit = textSplitter.splitDocuments(textSplit);\n      }\n\n      this.chunks = textSplit;\n      return;\n    }\n\n    throw new Error('HTML chunking requires either headers or sections to be specified');\n  }\n\n  async chunkJSON(options?: JsonChunkOptions): Promise<void> {\n    if (!options?.maxSize) {\n      throw new Error('JSON chunking requires maxSize to be specified');\n    }\n\n    const rt = new RecursiveJsonTransformer({\n      maxSize: options?.maxSize,\n      minSize: options?.minSize,\n    });\n\n    const textSplit = rt.transformDocuments({\n      documents: this.chunks,\n      ensureAscii: options?.ensureAscii,\n      convertLists: options?.convertLists,\n    });\n\n    this.chunks = textSplit;\n  }\n\n  async chunkLatex(options?: LatexChunkOptions): Promise<void> {\n    const rt = new LatexTransformer(options);","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/document/document.ts#L248-L284","documentation":"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.","triggerScenarios":"Calling doc.chunkJSON() or chunkJSON({}) / chunkJSON({ minSize: 100 }) where options.maxSize is undefined or 0/falsy.","commonSituations":"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.","solutions":["Provide maxSize in the options: doc.chunkJSON({ maxSize: 1024 }).","Ensure the value is defined and non-zero if sourced from configuration (add a default, e.g. maxSize ?? 1024).","Validate your options object before calling chunkJSON.","Review the JsonChunkOptions type to see which fields are required."],"exampleFix":"// before\nawait doc.chunkJSON({ minSize: 100 }); // maxSize missing\n\n// after\nawait doc.chunkJSON({ maxSize: 1024, minSize: 100 });","handlingStrategy":"validation","validationCode":"if (typeof options?.maxSize !== 'number' || options.maxSize <= 0) {\n  throw new Error('chunkJSON requires a positive maxSize');\n}","typeGuard":"function hasMaxSize(o: unknown): o is { maxSize: number } {\n  return typeof (o as any)?.maxSize === 'number' && (o as any).maxSize > 0;\n}","tryCatchPattern":"try {\n  await doc.chunkJSON(options);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('maxSize')) {\n    await doc.chunkJSON({ ...options, maxSize: options?.maxSize ?? 1024 });\n  } else throw e;\n}","preventionTips":["Define maxSize in shared chunking config with a default value.","Never spread partially-populated option objects without defaults.","Coerce config values with Number() and validate > 0 before use."],"tags":["rag","chunking","validation","configuration","json"],"backgroundTag":"missing-required-option","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}