Missing doc content for word document when list after a header

[tuan3w]

Bug

When a list appear after a heading, I see that it only keep header without content.
I check that it failed this check in the code:

https://github.com/docling-project/docling/blob/main/docling/backend/msword_backend.py#L1037-L1039

Steps to reproduce

Sorry I cannot share the document. But I added the screenshot of document part.
The parent as I see is a Section element so it fails the check:

SectionHeaderItem(self_ref='#/texts/25', parent=RefItem(cref='#/texts/22'), children=[], content_layer=<ContentLayer.BODY: 'body'>, label=<DocItemLabel.SECTION_HEADER: 'section_header'>, prov=[], orig='3 ĐIỀU KIỆN BẢO HÀNH', text='3 ĐIỀU KIỆN BẢO HÀNH', formatting=None, hyperlink=None, level=3)

I find that auto-creating a list group when it not satisfy check work but not sure about side effect.

Docling version

I use docling latest version 2.51

Python version

3.12

[dosubot]

This happens because the code in msword_backend.py expects list items to have a ListGroup as their parent, but after a heading (SectionHeaderItem), the parent is still the section header, so the check at lines 1037-1039 fails and the list content is skipped. This is a known issue and has been discussed in several places (example, example). The backend doesn't automatically create a ListGroup under a heading when a list follows, so the list is dropped.

A fix is to update the backend logic (likely in _add_list_item) to detect when the parent is a SectionHeaderItem and create a ListGroup under it for the list items. This pattern is already used elsewhere in the codebase to ensure lists are always under a ListGroup (see code). There have been recent improvements to list handling and numbering (PR #2100), but the core requirement remains: lists must be children of a ListGroup, not a section header.

If you're still seeing this in 2.51, check if your document structure after a heading is missing a ListGroup before the list. As a workaround, you can patch the backend to insert a ListGroup when a list follows a heading. This should resolve the missing content issue.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[dolfim-ibm]

We tried to reproduce the issue with a simple document and the output is complete as expected.

if you could share an example document we could try to understand the differences.

[tuan3w]

Hi @dolfim-ibm,

I created a simple one to reproduce the issue.
test.docx

Thanks

[KulovacNedim]

Hi @dolfim-ibm - I see something similar here:

In the red rectangle is the text that wasn't extracted by Dockling. After adding a line break before the missing line, the extraction worked well.

It looks like Dockling ignores for 'broken' internal XML structure for docx documents, which is kind of understandable, but it would be great if it could extract it in any way possible, instead of ignoring it and losing information. Simple because we can't predict if users (doc writers) broke something or not.

Here is a simplified doc where you can reproduce the issue:

text_3.docx

Thanks!

[tdgstoneman1]

Hi @dolfim-ibm - I see something similar here:

In the red rectangle is the text that wasn't extracted by Dockling. After adding a line break before the missing line, the extraction worked well.

It looks like Dockling ignores for 'broken' internal XML structure for docx documents, which is kind of understandable, but it would be great if it could extract it in any way possible, instead of ignoring it and losing information. Simple because we can't predict if users (doc writers) broke something or not.

Here is a simplified doc where you can reproduce the issue:

text_3.docx

Thanks!

I had the same issue, manually adding a continuous section break at the start of the missing line fixed it. Curious to know if you've found a solid way of doing this in Python.

[KulovacNedim]

Hi @dolfim-ibm - I see something similar here:

In the red rectangle is the text that wasn't extracted by Dockling. After adding a line break before the missing line, the extraction worked well.
It looks like Dockling ignores for 'broken' internal XML structure for docx documents, which is kind of understandable, but it would be great if it could extract it in any way possible, instead of ignoring it and losing information. Simple because we can't predict if users (doc writers) broke something or not.
Here is a simplified doc where you can reproduce the issue:
text_3.docx
Thanks!

I had the same issue, manually adding a continuous section break at the start of the missing line fixed it. Curious to know if you've found a solid way of doing this in Python.

I haven't even tried. I accepted the issue for now (my RAG pipeline might miss some info and be less precise) - hopefully the library maintainer will fix it somehow 🤞 If not, I'll try to figure out some replacement or manual fix.

[tdgstoneman]

Hi @dolfim-ibm - I see something similar here:

In the red rectangle is the text that wasn't extracted by Dockling. After adding a line break before the missing line, the extraction worked well.
It looks like Dockling ignores for 'broken' internal XML structure for docx documents, which is kind of understandable, but it would be great if it could extract it in any way possible, instead of ignoring it and losing information. Simple because we can't predict if users (doc writers) broke something or not.
Here is a simplified doc where you can reproduce the issue:
text_3.docx
Thanks!

I had the same issue, manually adding a continuous section break at the start of the missing line fixed it. Curious to know if you've found a solid way of doing this in Python.

I haven't even tried. I accepted the issue for now (my RAG pipeline might miss some info and be less precise) - hopefully the library maintainer will fix it somehow 🤞 If not, I'll try to figure out some replacement or manual fix.

FWIW I was able to find a super hacky workaround. In my case, the problem came from spans/frames embedded in the heading tags. Converting the doc to HTML, moving them out of the header, then converting the edited HTML file with Docling seems to work (still a fragile solution, though).

[dolfim-ibm]

Thanks for the test file, it should be a quick fix now.