Description

Fixes #2367

Background

Issue #2367 reports an IndexError: list index out of range when processing DOCX files with empty paragraph runs in _get_paragraph_elements. The original crash at c.runs[0] (line 395 in v2.36.1) has since been addressed with a bounds check (if c.runs and len(c.runs) > 0).

However, a closely related crash path in the same Hyperlink handling block remains: Path(c.address) on the line immediately above raises a TypeError when c.address is None. This occurs with internal bookmark hyperlinks (e.g., Table of Contents entries, cross-references), where the DOCX XML uses w:anchor instead of a relationship ID (r:id), causing python-docx's Hyperlink.address to return None.

Both bugs share the same root cause — incomplete defensive handling of Hyperlink objects from python-docx — and affect the same class of documents (DOCX files with certain structural patterns that cause complete parsing failure).

Changes

docling/backend/msword_backend.py (1 line)

• Added a conditional guard: hyperlink = Path(c.address) if c.address else None
• When c.address is None, hyperlink is set to None, which downstream logic already handles correctly — the hyperlink text is extracted and grouped with surrounding text instead of being wrapped in a Path object

tests/test_backend_msword.py (56 lines)

• Added regression test test_hyperlink_with_none_address
• Programmatically creates a DOCX containing an internal bookmark hyperlink (w:hyperlink with w:anchor, no r:id) via raw XML manipulation
• Converts the document via DocumentConverter and asserts:
  • No exception raised during conversion
  • Surrounding paragraph text is correctly extracted in the markdown export

Why this is safe

• The fix is a single conditional expression — no new branches, no changed return types
• Downstream code in the same method (lines 611-626) already handles hyperlink is None by grouping text normally rather than emitting a link
• All 12 existing DOCX backend tests continue to pass unchanged
• The fix follows the same defensive pattern already used for c.runs on the adjacent line

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have added tests that prove my fix is effective
• New and existing unit tests pass locally with my changes