DocLangDocSerializer raises ValueError for SectionHeaderItem.level=6 (unclamped +1 overflows heading token range)

[Steve-Allison]

Summary

DocLangDocSerializer raises ValueError: level must be in [1, 6] for any SectionHeaderItem with level == 6. This is a real, reachable case (not a synthetic edge case): DoclingDocument.SectionHeaderItem.level (LevelNumber) is allowed up to 100, and Docling's own PDF heading-hierarchy inference (HeadingHierarchyOptions, docling#3633, on by default with max_level=6 in docling-core's own default) legitimately produces level-6 headings on real documents. We hit this converting a 12-page PDF with a nested procedure list ("To configure the DaVinci Resolve Project Server:", etc.) — 10 of its headings landed at level 6.

Root cause

docling_core/transforms/serializer/doclang.py (current main, and every released version through 2.87.1 — this file is untouched in the 2.87.0→2.87.1 diff):

elif isinstance(item, SectionHeaderItem):
    wrap_open_token = DocLangVocabulary._create_heading_token(level=item.level + 1)

_create_heading_token → _create_level_open_token enforces the HEADING token's allowed range from _doclang_utils.py:

DocLangToken.HEADING: {DocLangAttributeKey.LEVEL: (1, 6)},

So item.level == 6 → level=7 → ValueError: level must be in [1, 6]. The +1 shift exists because level 1 is reserved for TitleItem, but nothing clamps the result back into range.

This is inconsistent with the library's own HTML serializer

docling_core/transforms/serializer/html.py performs the identical item.level + 1 computation for the same SectionHeaderItem, but clamps it:

section_level = min(item.level + 1, 6) if isinstance(item, SectionHeaderItem) else 1

(latex.py takes a third approach — it explicitly validates and raises a self-describing error, "LaTeX serializer: SectionHeaderItem.level must be in [1, 3]", since LaTeX only has 3 section depths. doctags.py passes item.level straight through with no transform.) doclang.py is the only one of the four that neither clamps, validates, nor passes through — it just lets the arithmetic overflow into the range check.

Repro

from docling_core.types.doc.document import DoclingDocument
from docling_core.transforms.serializer.doclang import DocLangDocSerializer, DocLangParams

doc = DoclingDocument(name="repro")
doc.add_heading(text="Top", level=1)
doc.add_heading(text="Deep", level=6)  # legal: LevelNumber allows up to 100

DocLangDocSerializer(doc=doc, params=DocLangParams()).serialize()
# ValueError: level must be in [1, 6]

Suggested fix

Mirror html.py's existing pattern — clamp instead of raising:

elif isinstance(item, SectionHeaderItem):
    wrap_open_token = DocLangVocabulary._create_heading_token(level=min(item.level + 1, 6))

(or, if silently flattening depth beyond 6 is undesirable, extend ALLOWED_ATTRIBUTE_RANGE[DocLangToken.HEADING]'s upper bound to accommodate the +1 shift against whatever the practical max SectionHeaderItem.level is expected to be — but the min(..., 6) clamp is the smallest change and matches existing precedent in the same file tree.)

Environment

• docling-core 2.87.0 (installed), confirmed still present verbatim on main and in the 2.87.1 tag as of 2026-07-16.
• macOS, Python 3.14.

[Steve-Allison]

While working around this, I found two related issues in the same area — flagging here since they share the same root trigger (Docling's own default heading-hierarchy inference, HeadingHierarchyOptions.max_level=6, legitimately producing level-6 SectionHeaderItems), even though each has a different failure mode. Happy to file these as separate issues instead if you'd prefer — let me know.

1. DocTags silently emits an unregistered token for the same level-6 case (no crash)

DocTagsTextSerializer doesn't raise for a level-6 SectionHeaderItem — but it silently emits a token outside docling-core's own registered vocabulary.

docling_core/transforms/serializer/doctags.py:

wrap_tag_token = DocumentToken.create_token_name_from_doc_item_label(
    label=item.label,
    **({"level": item.level} if isinstance(item, SectionHeaderItem) else {}),
)

docling_core/types/doc/tokens.py, create_token_name_from_doc_item_label:

if label == DocItemLabel.SECTION_HEADER:
    res = f"{_SECTION_HEADER_PREFIX}{level}"  # item.level used directly, no clamp/validation

But get_special_tokens() only pre-registers:

for i in range(6):  # 0..5 — NOT 6
    special_tokens += [f"<{_SECTION_HEADER_PREFIX}{i}>", f"</{_SECTION_HEADER_PREFIX}{i}>"]

Repro:

from docling_core.types.doc.document import DoclingDocument
from docling_core.types.doc.tokens import DocumentToken

doc = DoclingDocument(name="repro")
doc.add_heading(text="Top", level=1)
doc.add_heading(text="Deep", level=6)

text = doc.export_to_doctags()
known = set(DocumentToken.get_special_tokens())
print("<section_header_level_6>" in text)   # True
print("<section_header_level_6>" in known)  # False

No exception anywhere in the call path — the output file is well-formed and looks correct on casual inspection. This only bites a consumer that validates/tokenizes against the registered vocabulary (e.g. something trained on DocTags' closed special-token set via is_known_token()).

Suggested fix: extend get_special_tokens()'s range(6) to cover whatever levels SectionHeaderItem/HeadingHierarchyOptions can actually produce (at least range(7) to match the max_level=6 default), or validate item.level against the registry at serialization time.

2. FieldHeadingItem has the identical unclamped-arithmetic shape (level > 6, no +1 shift)

Same file, a different branch — FieldHeadingItem.level (also Annotated[int, Ge(1), Le(100)]) is used directly (no +1 shift here, unlike SectionHeaderItem):

elif isinstance(item, FieldHeadingItem):
    wrap_open_token = DocLangVocabulary._create_field_heading_token(level=item.level)

_create_field_heading_token enforces the same (1, 6) range as HEADING. Since there's no +1 shift, level=6 is fine (I initially assumed it would crash the same way as SectionHeaderItem and was wrong — verified it doesn't). It only overflows at level=7+:

from docling_core.types.doc.document import DoclingDocument
from docling_core.transforms.serializer.doclang import DocLangDocSerializer, DocLangParams

doc = DoclingDocument(name="repro")
doc.add_field_heading(text="Deep field", level=7)
DocLangDocSerializer(doc=doc, params=DocLangParams()).serialize()
# ValueError: level must be in [1, 6]

I have not seen this in practice — as far as I can tell nothing in the current docling extraction pipeline calls add_field_heading at any level, so this looks currently dormant rather than live. Flagging for completeness in case the same fix approach (whatever you land on for #1 above) should cover this branch too.