Section after table being incorrectly added as child of table header

[akowalsk]

Bug

For a reason I cannot determine, the attached file causes the parent/child relationships to be inappropriately mapped in the Docling Document object, causing the markdown (or any other) export to be incorrect. If you inspect the Document JSON, the table is correctly represented in the "Tables" array, but when you follow the refs to the second cell of the header (texts/3), it actually has a child, which is the header of the section following the table, and everything gets consolidated there on export.

{
      "self_ref": "#/texts/2",
      "parent": {
        "$ref": "#/groups/1"
      },
      "children": [],
      "content_layer": "body",
      "label": "section_header",
      "prov": [],
      "orig": "aaaaa",
      "text": "aaaaa",
      "level": 1
    },
    {
      "self_ref": "#/texts/3",
      "parent": {
        "$ref": "#/groups/2"
      },
      "children": [
        {
          "$ref": "#/texts/4"
        }
      ],
      "content_layer": "body",
      "label": "section_header",
      "prov": [],
      "orig": "aaaaaaaaa aaaaaa",
      "text": "aaaaaaaaa aaaaaa",
      "level": 1
    },
{
      "self_ref": "#/texts/4",
      "parent": {
        "$ref": "#/texts/3"
      },
      "children": [
        {
          "$ref": "#/groups/3"
        },
        {
          "$ref": "#/texts/8"
        },
        {
          "$ref": "#/tables/1"
        },
        {
          "$ref": "#/texts/11"
        }
      ],
      "content_layer": "body",
      "label": "section_header",
      "prov": [],
      "orig": "aaaaaaaa",
      "text": "aaaaaaaa",
      "level": 1
    },

...

Steps to reproduce

from docling.document_converter import DocumentConverter
filename='docling-table-bug.docx'
converter = DocumentConverter()
result = converter.convert(filename)
print(result.document.export_to_markdown()) 

Observe the generated markdown is

## aaaaaaaaaa

[aaaa aaaaaaaa aaa aaaaaaaa aaaaaaaaa aaaaaaaaaa aa aaaa aaaaaaaa aa aaaaaaaa aaaa aaaaaaaa. Aaa aaa aaaaaa aaaa aaaa aaa aaaaaa aaaaa aa aaaaaaaaaaa.  aa aaa aaaa aaaaaaaaa aaaa aaa aaa aaaaaaa aa aaaa aaaa.]

| ## aaaaa                                    |   ## aaaaaaaaa aaaaaa  ## aaaaaaaa  aaaaa aa *aaaaaaaaaa aaa aaaaaaaa aaaaaaaa* (aaa aaaaaaaaaa) aaa aaa aaaaa aaaaaa aaaaa aaa aaaaa aaaaaaaaaa aa aaaa aaaaaaa aa aaa aaaaa aaaaa.  [aaaaaaa aaaaaaaaaaa aaa aaaaaaaaaaaaa aaa aaaaa aaaa aaaaaa aaaa aaaa aaaaaaaaaaa aaa aaaaaaaa aaaaaaaa, aaaaaa aaa aaaaa aa aaa aaaaaa. aaaa aaaaaaaaaaa aaa aaaaaaaaaaaaa aa aaaaaaaaaaaa aaaaa.]  | ## aaaa [/](https://file+.vscode-resource.vscode-cdn.net/) Aaaaaaa   | ## aaaaaaaaaa               | |---------------------|-----------------------------| | aaa                 | aaaaaa aaa aaaaaaaaaaa aaaa | | aaa                 | aaaaaa aaaaa aaaaaaaa       | |
|---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| aaaaaaaa aaaaaaaaaaaaa aaaaaaaaaa aa        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            67547856 |
| aaaaaaaa aaaaaaaaaaaaa aa                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            68975669 |
| aaaaaaaa aaaaaaaaa aaa aaaaaaaaaa aaaaaaaaa |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           687956453 |
| aaaaaaaaa aaaaaaaaaaa aaaaaaaaa             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        896756454687 |

it puts the entire last half of the document into the header cell of the table.

Docling version

docling --version
2025-11-20 15:50:56,527 - INFO - Loading plugin 'docling_defaults'
2025-11-20 15:50:56,529 - INFO - Registered ocr engines: ['auto', 'easyocr', 'ocrmac', 'rapidocr', 'tesserocr', 'tesseract']
Docling version: 2.62.0
Docling Core version: 2.51.1
Docling IBM Models version: 3.10.2
Docling Parse version: 4.7.0
Python: cpython-312 (3.12.9)
Platform: macOS-15.7.2-arm64-arm-64bit

Python version

python --version
Python 3.12.9

docling-table-bug.docx

[dosubot]

This bug is caused by how Docling's DOCX parser manages the parent stack when processing tables and section headers. When a table cell contains rich content, the parser recursively walks the cell's XML and updates the parent stack (self.parents). If the parent stack isn't reset correctly after finishing a table, the next section header (or other block element) can be incorrectly attached as a child of the last table cell or header cell, which is why the section after your table is being nested under the table header in the document tree and markdown export.

This is a known class of issue in Docling's DOCX backend, especially after recent changes to table parsing and rich cell grouping [source]. The core problem is that _walk_linear and _handle_tables share and mutate the same parent tracking structure, but don't always restore it after processing nested content. This can cause subsequent elements (like section headers) to be attached to the wrong parent.

A code-level fix would involve ensuring that after processing a table (especially after handling rich cells), the parent stack is restored to the correct state before continuing with the next top-level element. This might mean saving and restoring self.parents or explicitly resetting the parent to the document body or the correct section group after each table.

Until this is fixed upstream, a workaround is to post-process the DoclingDocument JSON to re-parent any section headers that are children of table cells, or to avoid complex/nested content in table headers if possible.

For more details, see the relevant code and discussion here:
msword_backend.py - parent stack handling

To reply, just mention @dosu.

---

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

[akowalsk]

@dosu It appears that if I "unbold" the text in the header row of the first table, it fixes the issue. Does that help narrow down the fix?

[dosubot]

Yes, that’s a very helpful clue. When you bold the text in the table header, Docling’s DOCX parser treats the cell as “rich” content, which triggers a different parsing path: it recursively walks the cell’s XML and updates the parent stack. If the parent stack isn’t properly restored after this, the next section header (or other block element) can get incorrectly attached as a child of the table header cell—causing the bug you’re seeing. Unbolded header text keeps the cell “plain,” so this recursive parsing and parent stack mutation doesn’t happen, which is why unbolding is a workaround.

This narrows the root cause to how the parser handles formatted (bold) table cells and restores the parent stack after processing them. Fixing this will likely involve ensuring the parent stack is saved and restored correctly after parsing rich table cells. For now, avoiding bold formatting in table headers or post-processing the document structure are the most reliable workarounds. More details on the parsing logic and recent related fixes can be found in this section of the code and in recent PRs that improved rich cell handling.

To reply, just mention @dosu.

---

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

[akowalsk]

This appears to be fixed in the latest version (2.72.0) likely due to the PR closed issue it was mentioned in.

[akowalsk]

Sorry I messed this up by applying the fix (unbolding the headers) to my local copy and didn't notice. This isn't actually fixed on the original document. I will remove the new duplicate item that I just created.