HTML chunking requires either headers or sections to be spec

Error message

HTML chunking requires either headers or sections to be specified

What it means

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.

Source

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

      let textSplit = rt.transformDocuments(this.chunks);

      // Apply size-based splitting if maxSize is specified
      if (options?.maxSize) {
        const textSplitter = new RecursiveCharacterTransformer({
          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,
    });

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
await doc.chunkHTML({}); // throws

// after
await doc.chunkHTML({ headersToSplitOn: ['#', '##', '###'] });

Defensive patterns

Strategy: validation

Validate before calling

if (!options?.headersToSplitOn?.length && !options?.sections?.length) {
  throw new Error('HTML chunking needs headersToSplitOn or sections');
}

Type guard

function hasHtmlSplitOptions(o: unknown): o is { headersToSplitOn: string[] } | { sections: unknown[] } {
  const x = o as any;
  return Boolean(x?.headersToSplitOn?.length || x?.sections?.length);
}

Try / catch

try {
  await doc.chunkHTML(options);
} catch (e) {
  if (e instanceof Error && e.message.includes('headers or sections')) {
    await doc.chunkHTML({ headersToSplitOn: ['#', '##'] }); // default scheme
  } else throw e;
}

Prevention

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.

When it happens

Trigger: Calling doc.chunkHTML() or chunkHTML({}) with an options object that has neither headersToSplitOn nor sections defined.

Common situations: 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.

Related errors

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