The extract_items_range method generates a document with inconsistent hierarchy

[olivierantonelli]

Bug

The DoclingDocument.extract_items_range method may create an invalid DoclingDocument when the original document contains tables with RichTableCell cells.

During extract_items_range, GroupItems in the given range are renumbered, but the references to GroupItems in RichTableCell are not updated accordingly which results in an "IndexError: list index out of range" exception.

Steps to reproduce

from docling_core.types.doc import DoclingDocument, RichTableCell, TableCell, DocItemLabel, TableData, Formatting

doc = DoclingDocument(name="sample")

list_before_table = doc.add_list_group(name="A list")
doc.add_list_item(text="First item", parent=list_before_table)

table_item = doc.add_table(data=TableData(num_rows=2, num_cols=1))

cell = TableCell(text="R1C1", start_row_offset_idx=0, end_row_offset_idx=1, start_col_offset_idx=0, end_col_offset_idx=1)
doc.add_table_cell(table_item=table_item, cell=cell)

rich_group = doc.add_group(name="rich_cell_group", parent=table_item)
rich_cell = RichTableCell(start_row_offset_idx=1, end_row_offset_idx=2, start_col_offset_idx=0, end_col_offset_idx=1, ref=rich_group.get_ref(),)
doc.add_text(label=DocItemLabel.TEXT,text="R2C1", parent=rich_group, formatting=Formatting(italic=True))
doc.add_table_cell(table_item=table_item, cell=rich_cell)

# Here we create a new Docling document with the TableItem and all his childs
doc_with_only_the_table = doc.extract_items_range(start=doc.tables[0], end=doc.tables[0])

# export_to_markdown raises an "IndexError: list index out of range" exception
doc_with_only_the_table.export_to_markdown()

Here, without the export_to_markdown, 'doc_with_only_the_table' references '#/groups/1' which no longer exist:

doc_with_only_the_table.tables[0].data.grid[1][0].ref

RefItem(cref='#/groups/1')

list(doc_with_only_the_table.iterate_items(with_groups=True))

[(GroupItem(self_ref='#/body', parent=None, children=[RefItem(cref='#/tables/0')], content_layer=<ContentLayer.BODY: 'body'>, meta=None, name='_root_', label=<GroupLabel.UNSPECIFIED: 'unspecified'>),
  0),
 (TableItem(self_ref='#/tables/0', parent=RefItem(cref='#/body'), children=[RefItem(cref='#/groups/0')], content_layer=<ContentLayer.BODY: 'body'>, meta=None, label=<DocItemLabel.TABLE: 'table'>, prov=[], captions=[], references=[], footnotes=[], image=None, data=TableData(table_cells=[TableCell(bbox=None, row_span=1, col_span=1, start_row_offset_idx=0, end_row_offset_idx=1, start_col_offset_idx=0, end_col_offset_idx=1, text='R1C1', column_header=False, row_header=False, row_section=False, fillable=False), RichTableCell(bbox=None, row_span=1, col_span=1, start_row_offset_idx=1, end_row_offset_idx=2, start_col_offset_idx=0, end_col_offset_idx=1, text='', column_header=False, row_header=False, row_section=False, fillable=False, ref=RefItem(cref='#/groups/1'))], num_rows=2, num_cols=1, grid=[[TableCell(bbox=None, row_span=1, col_span=1, start_row_offset_idx=0, end_row_offset_idx=1, start_col_offset_idx=0, end_col_offset_idx=1, text='R1C1', column_header=False, row_header=False, row_section=False, fillable=False)], [RichTableCell(bbox=None, row_span=1, col_span=1, start_row_offset_idx=1, end_row_offset_idx=2, start_col_offset_idx=0, end_col_offset_idx=1, text='', column_header=False, row_header=False, row_section=False, fillable=False, ref=RefItem(cref='#/groups/1'))]]), annotations=[]),
  1),
 (GroupItem(self_ref='#/groups/0', parent=RefItem(cref='#/tables/0'), children=[RefItem(cref='#/texts/0')], content_layer=<ContentLayer.BODY: 'body'>, meta=None, name='rich_cell_group', label=<GroupLabel.UNSPECIFIED: 'unspecified'>),
  2),
 (TextItem(self_ref='#/texts/0', parent=RefItem(cref='#/groups/0'), children=[], content_layer=<ContentLayer.BODY: 'body'>, meta=None, label=<DocItemLabel.TEXT: 'text'>, prov=[], orig='R2C1', text='R2C1', formatting=Formatting(bold=False, italic=True, underline=False, strikethrough=False, script=<Script.BASELINE: 'baseline'>), hyperlink=None),
  3)]

Docling version

docling-core 2.51.1
Python: cpython 3.12.3
Platform: 6.6.87.2-microsoft-standard-WSL2

[dosubot]

Hi @olivierantonelli! I'm Dosu and I’m helping the docling-core team.

The root cause is that extract_items_range copies the selected items and their hierarchy, but does not update references in RichTableCell objects to match the new group indices in the extracted document. This leaves RichTableCell.ref fields pointing to group IDs (like #/groups/1) that no longer exist, which leads to the IndexError you observed.

The code path for extraction (add_node_items and _append_item_copies) deep-copies nodes and their children, but does not remap RichTableCell references. However, the internal _DocIndex.index method (used elsewhere for document merging and filtering) does handle this remapping: as it reindexes nodes, it updates RichTableCell.ref to the new self_ref of the copied group. This shows both that the remapping is necessary and how it could be implemented for extraction scenarios.

There is currently no documentation or open issues addressing this specific bug in docling-core 2.51.1. A potential workaround would be to manually update RichTableCell references after extraction, or to adapt the extraction logic to use the reference-updating approach found in _DocIndex.index.

For more details, see the relevant code and logic here.

To reply, just mention @dosu.

---

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

[olivierantonelli]

@dosu
yes, the _DocIndex.index method handles remapping and so is probably the way to go.

As a workaround example for the previous document, we can extract the rich table by copying the relevant elements as-is and then reindexing:

temporary_doc = DoclingDocument(name="Extracted table")
temporary_doc.tables = [doc.tables[0]]
temporary_doc.groups = [None, doc.groups[1]]
temporary_doc.texts = [None, doc.texts[1]]
temporary_doc.body.children.append(doc.tables[0].get_ref())
# Here we reindex with concatenate class method which use _DocIndex.index under the hood
extracted_table_doc = DoclingDocument.concatenate([temporary_doc])
print(extracted_table_doc.export_to_markdown())

| R1C1   |
|--------|
| *R2C1* |

[dosubot]

That's exactly right—using DoclingDocument.concatenate triggers a full reindex via _DocIndex.index, which updates all internal references (including RichTableCell.ref) to match the new structure. This resolves the reference inconsistency and avoids the IndexError you saw after extraction.

When using this workaround, just make sure your temporary document includes all referenced nodes (tables, groups, texts, etc.) and that the hierarchy is valid—otherwise, dangling references could remain after reindexing. Also, note that page numbers will be shifted to be contiguous in the new document, which is standard for concatenation and reindexing workflows. This approach is already used internally for normalization and is well-supported by the test suite, so it's a safe and robust solution for now.

If extract_items_range gets updated in the future to handle reference remapping directly, this extra step may no longer be necessary, but for now your method is the recommended practice.

To reply, just mention @dosu.

---

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