docling-project / docling-project/docling

Egret layout models fail with RuntimeError: label hyphen/underscore mismatch in _build_label_map

Open Beginner friendly
#3,053 5 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
66.4k
Forks
4.8k
Avg merge
3d 4h
Merged PRs (30d)
95

Description

### Bug

All Egret layout models (`DOCLING_LAYOUT_EGRET_MEDIUM`, `DOCLING_LAYOUT_EGRET_LARGE`, `DOCLING_LAYOUT_EGRET_XLARGE`) fail with a `RuntimeError` when initializing the layout pipeline. The Heron models work fine.

### Root Cause

The Egret model configs on HuggingFace use **hyphenated** label names in `id2label`:

```json
{
"3": "List-item",
"4": "Page-footer",
"5": "Page-header",
"7": "Section-header",
"11": "Document Index",
"13": "Checkbox-Selected",
"14": "Checkbox-Unselected",
"16": "Key-Value Region"
}
```

`_build_label_map()` in `layout_object_detection_model.py` normalizes with `.upper()` only, producing `LIST-ITEM`, but the `DocItemLabel` enum expects `LIST_ITEM` (underscore):

```python
label_enum_name = label_name.upper() # "List-item" -> "LIST-ITEM"
label_map[label_id] = DocItemLabel[label_enum_name] # KeyError: 'LIST-ITEM'
```

The Heron models use underscored labels (`list_item`, `page_footer`, etc.) which `.upper()` maps correctly to the enum.

### Steps to Reproduce

```python
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import LayoutOptions
from docling.datamodel.layout_model_specs import DOCLING_LAYOUT_EGRET_LARGE
from docling.document_converter import DocumentConverter, PdfFormatOption

converter = DocumentConverter(
format_options={
InputFormat.PDF: PdfFormatOption(
pipeline_options={"layout_options": LayoutOptions(model_spec=DOCLING_LAYOUT_EGRET_LARGE)}
),
}
)
# Convert any PDF
result = converter.convert("any_document.pdf")
```

### Error

```
File "docling/models/stages/layout/layout_object_detection_model.py", line 67, in _build_label_map
label_map[label_id] = DocItemLabel[label_enum_name]
KeyError: 'LIST-ITEM'

RuntimeError: Label 'List-item' (ID 3) from model config does not match any DocItemLabel enum value.
```

### Suggested Fix

Normalize hyphens and spaces to underscores in `_build_label_map`:

```python
label_enum_name = label_name.upper().replace("-", "_").replace(" ", "_")
```

### Affected Models

Verified all three Egret model configs on HuggingFace use hyphenated labels:
- `docling-project/docling-layout-egret-medium`
- `docling-project/docling-layout-egret-large`
- `docling-project/docling-layout-egret-xlarge`

Heron models (`docling-layout-heron`, `docling-layout-heron-101`) use underscored labels and work correctly.

### Docling version

docling 2.75.0

### Python version

Python 3.14.3

Contributor guide

Open the contributing guide

Research direction

Start in docling/models/stages/layout/layout_object_detection_model.py at _build_label_map, then run the DocumentConverter reproduction with DOCLING_LAYOUT_EGRET_LARGE. Compare the Egret and Heron label names and verify that all three Egret models initialize and convert a PDF without the label mismatch, while Heron behavior remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
machine-learning
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.