~30% of my HTML pages are not converted after upgrade to Docling 2.55.0

[tysonite]

Bug

Right after I upgraded to Docling 2.55.0, around 30% of my HTML pages are not parsed. Such behavior was not observed on the Docling versions prior to 2.55.0. Hereafter is the simple step-by-step scenario to reproduce the issue. The HTML data is anonymized and limited to the scenario where the issue reproduces. Other cases may be present that I am not aware yet of. Also, I guess the issue might be related to #2324.

Steps to reproduce

The Python script to parse HTML page:

import logging
import json
from pathlib import Path

from docling.datamodel.base_models import InputFormat
from docling.datamodel.document import InputDocument
from docling.backend.html_backend import HTMLDocumentBackend

file_path = "./bad.html"
file = Path(file_path)


in_doc = InputDocument(
    path_or_stream=file,
    format=InputFormat.HTML,
    backend=HTMLDocumentBackend,
    filename=file_path,
)
backend = HTMLDocumentBackend(in_doc=in_doc, path_or_stream=file)
try:
    dl_doc = backend.convert()
    docling_text = json.dumps(dl_doc.export_to_dict())
except Exception:
    logging.exception(f"Unable to parse {file_path} using Docling")

The bad.html:

<div class="table-wrap">
    <table class="wrapped fixed-table confluenceTable">
        <colgroup>
            <col style="width: 87.0px;" />
            <col style="width: 99.0px;" />
            <col style="width: 459.0px;" />
            <col style="width: 547.0px;" />
            <col style="width: 579.0px;" />
        </colgroup>
        <tbody>
            <tr>
                <th class="confluenceTh">...</th>
                <th class="confluenceTh">
                    <p>Screen</p>
                </th>
                <th class="confluenceTh">...</th>
                <th class="confluenceTh">...</th>
                <th class="confluenceTh">...</th>
            </tr>
            <tr>
                <td class="confluenceTd">
                    <h2 id="...">...</h2>
                </td>
                <td class="confluenceTd"><br /></td>
                <td class="confluenceTd"><br /></td>
                <td class="confluenceTd"><br /></td>
                <td class="confluenceTd"><br /></td>
            </tr>
            <tr>
                <td class="confluenceTd">...</td>
                <td class="confluenceTd">...</td>
                <td class="confluenceTd">
                    <div class="content-wrapper">
                        <p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
                                    class="confluence-embedded-image" draggable="false" height="250"
                                    src="..."></span>
                        </p>
                        <p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
                                    class="confluence-embedded-image" draggable="false" height="250"
                                    src="..."></span>
                        </p>
                        <p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
                                    class="confluence-embedded-image confluence-thumbnail" draggable="false" height="65"
                                    src="..."></span><span
                                class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
                                    class="confluence-embedded-image confluence-thumbnail" draggable="false" height="67"
                                    src="..."></span>
                        </p>
                    </div>
                </td>
                <td class="confluenceTd">
                    <p>...</p>
                    <ul>
                        <li>...</li>
                        <li>...</li>
                    </ul>
                    <p>...</p>
                    <ul>
                        <li>...</li>
                        <li>...</li>
                    </ul>
                </td>
                <td class="confluenceTd"><br /></td>
            </tr>
            <tr>
                <td class="confluenceTd">...</td>
                <td class="confluenceTd">
                    <h3 id="...">...</h3>
                </td>
                <td class="confluenceTd">
                    <div class="content-wrapper">
                        <p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
                                    class="confluence-embedded-image" draggable="false" height="250"
                                    src="..."></span>
                        </p>
                    </div>
                </td>
                <td class="confluenceTd">
                    <p>...<span style="color: rgb(255,0,0);">...
                            <img class="emoticon emoticon-question"
                                src="..."
                                data-emoticon-name="question" alt="(question)"
                                data-emoji-short-name=":question:" /></span>...</p>
                    <h4 id="...">...</h4>
                    <ul>
                        <li>...</li>
                        <li><span style="color: rgb(255,0,0);">...<img class="emoticon emoticon-question"
                                    src="..."
                                    data-emoticon-name="question" alt="(question)" data-emoji-short-name=":question:" />
                                ...</span></li>
                    </ul>
                    <h4 id="...">...</h4>
                    <p>...<span
                            style="color: rgb(255,0,0);">...</span> <img class="emoticon emoticon-question"
                            src="..."
                            data-emoticon-name="question" alt="(question)" data-emoji-short-name=":question:" />...</p>
                    <p><span style="color: rgb(255,0,0);">...<img class="emoticon emoticon-question"
                                src="..."
                                data-emoticon-name="question" alt="(question)"
                                data-emoji-short-name=":question:" /></span></p>
                    <h4 id="...">...</h4>
                    <div class="table-wrap">
                        <table class="wrapped confluenceTable">
                            <tbody>
                                <tr>
                                    <th class="confluenceTh">...</th>
                                    <th class="confluenceTh">...</th>
                                    <th class="confluenceTh">...</th>
                                </tr>
                                <tr>
                                    <td class="confluenceTd">...</td>
                                    <td class="confluenceTd">...<span
                                            style="color: rgb(255,0,0);">...</span></td>
                                    <td class="confluenceTd">...</td>
                                </tr>
                                <tr>
                                    <td class="confluenceTd">...</td>
                                    <td class="confluenceTd">...<span
                                            style="color: rgb(255,0,0);">...</span></td>
                                    <td class="confluenceTd">...</td>
                                </tr>
                            </tbody>
                        </table>
                    </div>
                </td>
            </tr>
            <tr>
                <td colspan="1" class="confluenceTd">...</td>
                <td colspan="1" class="confluenceTd">
                    <h3 id="...">...</h3>
                </td>
                <td colspan="1" class="confluenceTd">
                    <div class="content-wrapper">
                        <p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
                                    class="confluence-embedded-image" draggable="false" height="250"
                                    src="..."></span>
                        </p>
                    </div>
                </td>
                <td colspan="1" class="confluenceTd">...</td>
                <td colspan="1" class="confluenceTd"><br /></td>
            </tr>
        </tbody>
    </table>
</div>

The error:

ERROR:root:Unable to parse ./bad.html using Docling
Traceback (most recent call last):
  File "/home/docqa/test_docling.py", line 21, in <module>
    dl_doc = backend.convert()
  File "/home/docqa/.venv/lib/python3.10/site-packages/docling/backend/html_backend.py", line 281, in convert
    self._walk(content, doc)
  File "/home/docqa/.venv/lib/python3.10/site-packages/docling/backend/html_backend.py", line 521, in _walk
    wk3 = self._walk(node, doc)
  File "/home/docqa/.venv/lib/python3.10/site-packages/docling/backend/html_backend.py", line 517, in _walk
    blk = self._handle_block(node, doc)
  File "/home/docqa/.venv/lib/python3.10/site-packages/docling/backend/html_backend.py", line 1038, in _handle_block
    self.parse_table_data(tag, doc, docling_table, num_rows, num_cols)
  File "/home/docqa/.venv/lib/python3.10/site-packages/docling/backend/html_backend.py", line 401, in parse_table_data
    HTMLDocumentBackend.process_rich_table_cells(
  File "/home/docqa/.venv/lib/python3.10/site-packages/docling/backend/html_backend.py", line 327, in process_rich_table_cells
    doc.delete_items(node_items=[pr_item])
  File "/home/docqa/.venv/lib/python3.10/site-packages/docling_core/types/doc/document.py", line 2057, in delete_items
    self._delete_items(refs=refs)
  File "/home/docqa/.venv/lib/python3.10/site-packages/docling_core/types/doc/document.py", line 2259, in _delete_items
    raise ValueError(
ValueError: Cannot find all provided RefItems in doc: ['#/texts/0']

Docling version

2025-10-01 14:11:57,666 - INFO - Loading plugin 'docling_defaults'
2025-10-01 14:11:57,667 - INFO - Registered ocr engines: ['easyocr', 'ocrmac', 'rapidocr', 'tesserocr', 'tesseract']
Docling version: 2.55.0
Docling Core version: 2.48.3
Docling IBM Models version: 3.9.1
Docling Parse version: 4.5.0
Python: cpython-310 (3.10.12)
Platform: Linux-6.8.0-79-generic-x86_64-with-glibc2.35

Python version

Python 3.10.12

[dosubot]

This is a regression introduced by the rich tables refactor in Docling 2.55.0 (PR #2324). The new table parsing logic changed how references to table cell content are managed, and in complex or nested tables, this can cause reference mismatches and the ValueError: Cannot find all provided RefItems in doc you’re seeing. This is especially likely with deeply nested tables or multiple paragraphs inside table cells, which Docling currently flattens, sometimes losing content or structure and breaking reference tracking source.

There’s no config flag or patch to fully resolve this yet. Workarounds include preprocessing your HTML to replace consecutive <p> tags inside <td> with <br> tags, or creating a custom serializer to preserve paragraph separation. For some documents, converting to PDF and running Docling on the PDF can yield better results. If you want to experiment, you can also try toggling between “accurate” and “fast” table extraction modes or disabling cell matching (do_cell_matching=False), but results may vary source.

This bug is tracked and discussed in issue #2330. There are no follow-up fixes merged yet, so monitoring that thread is the best way to stay updated.

To reply, just mention @dosu.

---

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

[maxmnemonic]

Thanks for giving an example @tysonite ! Looking into it...

[maxmnemonic]

@tysonite , this PR should fix you issue: #2394

[tysonite]

@tysonite , this PR should fix you issue: #2394

Thank you @maxmnemonic . I tried your PR and it seems all my html pages were converted successfully. However, I noticed tons of INFO log messages like "deleted item in tree at stack: (4, 4, 5) => #/texts/26". I am not sure what to do with them in a regular setup, thus, asking - is it possible to move them to DEBUG level instead of INFO if they are necessary for the development?

See the total number of those messages in my log below:

$ cat startup_2_55_x.log |grep "deleted item in tree at stack"|wc -l
301048

Also, there are about 500 errors like "Error while making rich table: Cannot find all provided RefItems in doc: ['#/texts/2891']", what does it mean? Docling tables were not produced from the HTML content?

$ cat startup_2_55_x.log |grep "Error while making rich table"|wc -l
475

[maxmnemonic]

@tysonite good suggestion! I need to do few small touch ups in that PR, let me check what I can do for logging.
Regarding error "Error while making rich table" means that there was some issue with a content of a cell in a table, most likely table will be created, but would be nice to check what happens to the content. Any chance you could give an example of an HTML that throws this error?
Many thanks in advance.

[maxmnemonic]

@tysonite this should silence the logs, once released: docling-project/docling-core#400

[tysonite]

@tysonite good suggestion! I need to do few small touch ups in that PR, let me check what I can do for logging. Regarding error "Error while making rich table" means that there was some issue with a content of a cell in a table, most likely table will be created, but would be nice to check what happens to the content. Any chance you could give an example of an HTML that throws this error? Many thanks in advance.

THank you for the fixes, @maxmnemonic . I have created a ticket #2408 for " Error while making rich table" as you suggested.