Word Document Extraction (WordExtractor)#

Overview#

WordExtractor (api/core/rag/extractor/word_extractor.py) parses .docx files for Dify's RAG ingestion pipeline, producing a single Document with Markdown-formatted content that preserves images, hyperlinks, and tables. It is dispatched by ExtractProcessor for .docx files in both dify and unstructured ETL modes.

Key entry points:

Remote File Handling & SSRF Protection#

When file_path is a URL, __init__ downloads the file using remote_fetcher.make_request("GET", ...) 1 and writes the response to a tempfile.NamedTemporaryFile 2. The temp file's path is then used as self.file_path for the rest of the extraction lifecycle.

Remote downloads previously used httpx.get directly; PR #31678 replaced this with remote_fetcher, which routes through ssrf_proxy to prevent SSRF attacks 3.

⚠️ Windows PermissionError (Known Issue)#

On Windows, NamedTemporaryFile cannot be reopened while its file handle is still open. When python-docx opens self.file_path (the temp file), Windows raises PermissionError: [Errno 13] Permission denied. The workaround — delete=False + manual os.unlink() in close() — is not yet implemented; a # TODO comment marks the spot 4. Tracked as GitHub Issue #39889.

Image Extraction#

_extract_images_from_docx() iterates doc.part.rels and handles two cases:

• Embedded images (rel.is_external == False): reads rel.target_part.blob, saves to external storage under image_files/<tenant_id>/<uuid>.<ext>, creates an UploadFile record, and maps the part object → ![image](<FILES_URL>/files/<id>/file-preview) 5.
• External image URLs (rel.is_external == True): downloads via remote_fetcher, saves identically, and maps r_id → the same preview URL format 6.

The preview URL base is dify_config.FILES_URL 7. PR #35975 fixed a regression where INTERNAL_FILES_URL was used instead, making images unreachable from browsers 8.

UploadFile records are batched and committed after all images are processed; if _session is injected by the caller, the caller controls the commit 9.

Hyperlink Extraction#

Two hyperlink formats are handled inside parse_paragraph():

1. Modern w:hyperlink XML elements — process_hyperlink() reads r:id, resolves the relationship on doc.part.rels, and emits [text](url) for external relationships. Fixed in PR #30360 10.

2. Legacy HYPERLINK field codes (w:fldChar / w:instrText) — a state machine tracks begin / separate / end transitions 11, extracts the URL via regex from instrText, and captures the visible text from runs between separate and end.

Both formats are also handled inside table cells via _parse_cell_paragraph(). PR #33224 fixed cell-level parsing to support http and mailto links that were previously missed 12.

w:anchor internal bookmarks are intentionally left as plain text — only externally-referenced links with an r:id relationship are converted to Markdown 13.

Table Parsing & Pipe Escaping#

Tables are rendered as GFM by _table_to_markdown() via the chain _parse_row() → _parse_cell() → _parse_cell_paragraph(). Merged cells (column-span via cell.grid_span) are handled by filling spanned columns with empty strings 14.

Cell content containing literal | characters must be escaped to \|; without escaping, the pipe becomes an extra column separator, corrupting the Markdown table row. PR #41991 added this escaping 15. PR #42002 included a related fix for Markdown table corruption across multiple extractors 16.

Text Box Extraction (Silent-Drop Fix)#

parse_docx() iterates doc.iter_inner_content() and processes only Paragraph and Table blocks 17. Text inside Word text boxes (w:txbxContent) lives in a separate drawing subtree and was never reached, silently dropping callouts, sidebars, and pull quotes.

PR #42334 introduced parse_text_boxes(), which finds w:txbxContent descendants in each paragraph's XML and routes them through the existing parse_paragraph() path 18. Word stores text boxes twice inside mc:AlternateContent (once in mc:Choice, once in mc:Fallback); the fix skips mc:Fallback copies by checking ancestor tags to prevent duplicate extraction.

Key Files & References#

Related PRs:

• PR #30360 — Correct DOCX hyperlink extraction 10
• PR #31678 — SSRF fix for WordExtractor URL download 3
• PR #33224 — Fix mailto/http links in table cells 12
• PR #35975 — Fix image rendering in knowledge base 8
• PR #41991 — Escape pipe characters in table cells 15
• PR #42002 — Resolve Markdown table corruption 16
• PR #42334 — Read text inside Word text boxes 18