{"record":{"id":"f0ec8b0859ada975","repo":"mastra-ai/mastra","slug":"html-chunking-requires-either-headers-or-sections","errorCode":null,"errorMessage":"HTML chunking requires either headers or sections to be specified","messagePattern":"HTML chunking requires either headers or sections to be specified","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/document/document.ts","lineNumber":261,"sourceCode":"      let textSplit = rt.transformDocuments(this.chunks);\n\n      // Apply size-based splitting if maxSize is specified\n      if (options?.maxSize) {\n        const textSplitter = new RecursiveCharacterTransformer({\n          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","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/document/document.ts#L243-L279","documentation":"chunkHTML on Document supports two mutually compatible modes: splitting by markdown-style headers (headersToSplitOn) or by explicit sections. If neither headers nor sections is provided in the HTMLChunkOptions, there is no way to determine chunk boundaries, so the library throws this configuration error.","triggerScenarios":"Calling doc.chunkHTML() or chunkHTML({}) with an options object that has neither headersToSplitOn nor sections defined.","commonSituations":"Switching from chunkRecursive/chunkCharacter (where empty options are fine) to HTML chunking without realizing it requires a splitting scheme; copying example code and deleting the headers config; building options conditionally where both fields end up undefined.","solutions":["Pass headers to split on: chunkHTML({ headersToSplitOn: ['#', '##'] }) for header-based chunking.","Or pass explicit sections: chunkHTML({ sections: [...] }) if you already know the boundaries.","If you just want generic text chunking of HTML content, use chunkRecursive or chunkCharacter instead.","Add a guard in your code that defaults to a standard header set when neither option is provided."],"exampleFix":"// before\nawait doc.chunkHTML({}); // throws\n\n// after\nawait doc.chunkHTML({ headersToSplitOn: ['#', '##', '###'] });","handlingStrategy":"validation","validationCode":"if (!options?.headersToSplitOn?.length && !options?.sections?.length) {\n  throw new Error('HTML chunking needs headersToSplitOn or sections');\n}","typeGuard":"function hasHtmlSplitOptions(o: unknown): o is { headersToSplitOn: string[] } | { sections: unknown[] } {\n  const x = o as any;\n  return Boolean(x?.headersToSplitOn?.length || x?.sections?.length);\n}","tryCatchPattern":"try {\n  await doc.chunkHTML(options);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('headers or sections')) {\n    await doc.chunkHTML({ headersToSplitOn: ['#', '##'] }); // default scheme\n  } else throw e;\n}","preventionTips":["Always pass headersToSplitOn or sections when using HTML chunking.","Provide a default header set in shared config helpers.","Use chunkRecursive if you don't need structure-aware splitting."],"tags":["rag","chunking","validation","configuration","html"],"backgroundTag":"missing-required-option","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}