fix(docx): add timeout and isolated profile to LibreOffice conversions (#3820)

DanielNg0729 · web-flow · commit 2093ad3ba058 · 2026-07-28T14:18:26.000+02:00
* fix(docx): add timeout and isolated profile to LibreOffice conversions The shared LibreOffice->PDF converter used by the DOCX and PPTX backends ran soffice with no timeout, so a hung conversion blocked the calling thread forever. The XLSX backend duplicated the same subprocess call with its own 60s timeout, but neither passed -env:UserInstallation, so concurrent conversions collided on LibreOffice's default profile lock and failed intermittently and silently. Give every LibreOffice invocation a bounded timeout and its own throwaway profile directory, and drop the XLSX backend's duplicated logic in favor of the shared helper. Resolves #3819 Signed-off-by: Daniel Nguyen <danielnguyenh07@gmail.com> * fix(docx): isolate LibreOffice profile in convert_to_modern_format too convert_with_libreoffice already had -env:UserInstallation profile isolation from the previous commit, but convert_to_modern_format (used for legacy .doc/.xls/.ppt -> modern Open XML conversion) still shared the default LibreOffice profile, so it remained vulnerable to the same concurrent-conversion lock contention. Extract the isolated-profile setup into a shared _isolated_libreoffice_profile context manager so both conversion paths use it instead of duplicating the logic a third time. Also add type annotations to convert_with_libreoffice and move the previous inline comments into docstrings per review feedback. Signed-off-by: Daniel Nguyen <danielnguyenh07@gmail.com> --------- Signed-off-by: Daniel Nguyen <danielnguyenh07@gmail.com>
diff --git a/docling/backend/docx/drawingml/utils.py b/docling/backend/docx/drawingml/utils.py
@@ -3,17 +3,26 @@
 import os
 import shutil
 import subprocess
+from collections.abc import Iterator
+from contextlib import contextmanager
 from io import BytesIO
 from pathlib import Path
 from tempfile import mkdtemp
-from typing import TYPE_CHECKING, Callable, Optional
+from typing import TYPE_CHECKING, Callable, Final, Optional
 
 import pypdfium2
 from PIL import Image, ImageChops
 
 if TYPE_CHECKING:
     from docx.document import Document
 
+LIBREOFFICE_TIMEOUT_S: Final[int] = 60
+"""Maximum seconds to wait for a single LibreOffice conversion.
+
+Without this, a hung ``soffice`` process (e.g. a modal dialog it can't
+show in headless mode) blocks the calling thread forever.
+"""
+
 
 def get_libreoffice_cmd(raise_if_unavailable: bool = False) -> Optional[str]:
     """Return the libreoffice cmd and optionally test it."""
@@ -46,6 +55,27 @@ def get_libreoffice_cmd(raise_if_unavailable: bool = False) -> Optional[str]:
     return libreoffice_cmd
 
 
+@contextmanager
+def _isolated_libreoffice_profile() -> Iterator[str]:
+    """Yield a ``-env:UserInstallation`` argument backed by a throwaway profile.
+
+    LibreOffice takes an exclusive lock on its user profile directory.
+    Without this, concurrent conversions (parallel workers, docling-serve
+    handling simultaneous requests) share the default profile and collide
+    on that lock, causing conversions to fail intermittently and silently.
+
+    Yields:
+        A ``-env:UserInstallation=<uri>`` CLI argument pointing at a freshly
+        created, empty profile directory. The directory is removed again
+        once the ``with`` block exits.
+    """
+    profile_dir = Path(mkdtemp(prefix="docling_lo_profile_"))
+    try:
+        yield f"-env:UserInstallation={profile_dir.as_uri()}"
+    finally:
+        shutil.rmtree(profile_dir, ignore_errors=True)
+
+
 def convert_to_modern_format(
     source: BytesIO | Path,
     source_suffix: str,
@@ -93,21 +123,23 @@ def convert_to_modern_format(
         else:
             input_path = source
 
-        subprocess.run(
-            [
-                libreoffice_cmd,
-                "--headless",
-                "--convert-to",
-                target_suffix,
-                "--outdir",
-                str(tmp_dir),
-                str(input_path),
-            ],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=True,
-            timeout=timeout_s,
-        )
+        with _isolated_libreoffice_profile() as profile_arg:
+            subprocess.run(
+                [
+                    libreoffice_cmd,
+                    profile_arg,
+                    "--headless",
+                    "--convert-to",
+                    target_suffix,
+                    "--outdir",
+                    str(tmp_dir),
+                    str(input_path),
+                ],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=True,
+                timeout=timeout_s,
+            )
 
         converted_path = tmp_dir / (input_path.stem + "." + target_suffix)
         if not converted_path.exists():
@@ -132,21 +164,38 @@ def get_docx_to_pdf_converter() -> Optional[Callable]:
 
     if libreoffice_cmd:
 
-        def convert_with_libreoffice(input_path, output_path):
-            subprocess.run(
-                [
-                    libreoffice_cmd,
-                    "--headless",
-                    "--convert-to",
-                    "pdf",
-                    "--outdir",
-                    os.path.dirname(output_path),
-                    input_path,
-                ],
-                stdout=subprocess.DEVNULL,
-                stderr=subprocess.DEVNULL,
-                check=True,
-            )
+        def convert_with_libreoffice(
+            input_path: str | Path, output_path: str | Path
+        ) -> None:
+            """Convert a DOCX/PPTX file to PDF via LibreOffice.
+
+            Runs the conversion in its own throwaway LibreOffice profile
+            (see ``_isolated_libreoffice_profile``) with a bounded timeout,
+            so a hung ``soffice`` process cannot block the calling thread
+            forever and concurrent conversions cannot collide on the
+            default profile lock.
+
+            Args:
+                input_path: Path to the source file to convert.
+                output_path: Desired path for the converted PDF.
+            """
+            with _isolated_libreoffice_profile() as profile_arg:
+                subprocess.run(
+                    [
+                        libreoffice_cmd,
+                        profile_arg,
+                        "--headless",
+                        "--convert-to",
+                        "pdf",
+                        "--outdir",
+                        os.path.dirname(output_path),
+                        input_path,
+                    ],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    check=True,
+                    timeout=LIBREOFFICE_TIMEOUT_S,
+                )
 
             expected_output = os.path.join(
                 os.path.dirname(output_path),
diff --git a/docling/backend/msexcel_backend.py b/docling/backend/msexcel_backend.py
@@ -4,7 +4,6 @@
 import logging
 import posixpath
 import shutil
-import subprocess
 import warnings
 from copy import deepcopy
 from datetime import datetime
@@ -49,7 +48,7 @@
 from docling.backend.docx.drawingml.utils import (
     convert_to_modern_format,
     crop_whitespace,
-    get_libreoffice_cmd,
+    get_docx_to_pdf_converter,
 )
 from docling.datamodel.backend_options import MsExcelBackendOptions
 from docling.datamodel.base_models import FormatToMimeType, InputFormat
@@ -272,10 +271,6 @@ class MsExcelDocumentBackend(DeclarativeDocumentBackend, PaginatedDocumentBacken
           parsing, so threaded comments are not available for that format.
     """
 
-    # Maximum seconds to wait for a single LibreOffice EMF/WMF conversion.
-    # Raise this value if conversions time out on unusually large or complex files.
-    LIBREOFFICE_TIMEOUT_S: Final[int] = 60
-
     # Maximum uncompressed byte sizes accepted when reading members from the XLSX zip.
     # These caps guard against decompression-bomb payloads in drawing XML / image files.
     _MAX_DRAWING_BYTES: Final[int] = 10 * 1024 * 1024  # 10 MB
@@ -1147,36 +1142,11 @@ def _get_libreoffice_converter(self) -> Callable | None:
             return self.xlsx_to_pdf_converter
 
         self.xlsx_to_pdf_converter_init = True
-        libreoffice_cmd = get_libreoffice_cmd()
-        if libreoffice_cmd is None:
+        self.xlsx_to_pdf_converter = get_docx_to_pdf_converter()
+        if self.xlsx_to_pdf_converter is None:
             _log.debug(
                 "LibreOffice not found — EMF/WMF images in XLSX will be skipped."
             )
-            self.xlsx_to_pdf_converter = None
-            return None
-
-        def _convert(input_path: Path, output_path: Path) -> None:
-            subprocess.run(
-                [
-                    libreoffice_cmd,
-                    "--headless",
-                    "--convert-to",
-                    "pdf",
-                    "--outdir",
-                    str(output_path.parent),
-                    str(input_path),
-                ],
-                stdout=subprocess.DEVNULL,
-                stderr=subprocess.DEVNULL,
-                check=True,
-                timeout=self.LIBREOFFICE_TIMEOUT_S,
-            )
-            # LibreOffice names the output after the input stem
-            expected = output_path.parent / (input_path.stem + ".pdf")
-            if expected != output_path:
-                expected.rename(output_path)
-
-        self.xlsx_to_pdf_converter = _convert
         return self.xlsx_to_pdf_converter
 
     def _convert_emf_to_pil(self, image_bytes: bytes) -> PILImage.Image | None:
diff --git a/tests/test_drawingml_utils.py b/tests/test_drawingml_utils.py
@@ -0,0 +1,121 @@
+import subprocess
+from io import BytesIO
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from docling.backend.docx.drawingml import utils as drawingml_utils
+
+
+def _track_mkdtemp(monkeypatch) -> list[Path]:
+    created_dirs: list[Path] = []
+    real_mkdtemp = drawingml_utils.mkdtemp
+
+    def tracking_mkdtemp(*args, **kwargs):
+        path = real_mkdtemp(*args, **kwargs)
+        created_dirs.append(Path(path))
+        return path
+
+    monkeypatch.setattr(drawingml_utils, "mkdtemp", tracking_mkdtemp)
+    return created_dirs
+
+
+def test_convert_with_libreoffice_uses_timeout_and_isolated_profile(
+    monkeypatch, tmp_path
+):
+    monkeypatch.setattr(
+        drawingml_utils, "get_libreoffice_cmd", lambda: "/usr/bin/soffice"
+    )
+    created_profile_dirs = _track_mkdtemp(monkeypatch)
+
+    captured_args: list[str] = []
+    captured_kwargs: dict = {}
+
+    def fake_run(args, **kwargs):
+        captured_args.extend(args)
+        captured_kwargs.update(kwargs)
+        # The isolated profile dir must exist while the "conversion" runs.
+        assert created_profile_dirs[-1].exists()
+        # Mirror LibreOffice's real behavior of writing the PDF next to the
+        # input, named after the input's stem.
+        (tmp_path / "drawing_only.pdf").write_bytes(b"%PDF-1.4")
+        return MagicMock(returncode=0)
+
+    monkeypatch.setattr(drawingml_utils.subprocess, "run", fake_run)
+
+    converter = drawingml_utils.get_docx_to_pdf_converter()
+    assert converter is not None
+
+    input_path = tmp_path / "drawing_only.docx"
+    output_path = tmp_path / "drawing_only.pdf"
+    input_path.write_bytes(b"")
+
+    converter(input_path, output_path)
+
+    assert captured_kwargs["timeout"] == drawingml_utils.LIBREOFFICE_TIMEOUT_S
+
+    profile_flag = next(
+        a for a in captured_args if str(a).startswith("-env:UserInstallation=")
+    )
+    assert created_profile_dirs[-1].as_uri() in profile_flag
+
+    # The isolated profile directory is cleaned up after the call.
+    assert not created_profile_dirs[-1].exists()
+
+
+def test_convert_with_libreoffice_cleans_up_profile_on_timeout(monkeypatch, tmp_path):
+    monkeypatch.setattr(
+        drawingml_utils, "get_libreoffice_cmd", lambda: "/usr/bin/soffice"
+    )
+    created_profile_dirs = _track_mkdtemp(monkeypatch)
+
+    def fake_run(args, **kwargs):
+        raise subprocess.TimeoutExpired(cmd=args, timeout=kwargs.get("timeout"))
+
+    monkeypatch.setattr(drawingml_utils.subprocess, "run", fake_run)
+
+    converter = drawingml_utils.get_docx_to_pdf_converter()
+    assert converter is not None
+
+    input_path = tmp_path / "drawing_only.docx"
+    output_path = tmp_path / "drawing_only.pdf"
+    input_path.write_bytes(b"")
+
+    with pytest.raises(subprocess.TimeoutExpired):
+        converter(input_path, output_path)
+
+    # A hung/killed conversion must not leak its profile directory.
+    assert not created_profile_dirs[-1].exists()
+
+
+def test_convert_to_modern_format_uses_isolated_profile(monkeypatch):
+    monkeypatch.setattr(
+        drawingml_utils, "get_libreoffice_cmd", lambda: "/usr/bin/soffice"
+    )
+    created_profile_dirs = _track_mkdtemp(monkeypatch)
+
+    captured_kwargs: dict = {}
+
+    def fake_run(args, **kwargs):
+        captured_kwargs.update(kwargs)
+        # The isolated profile dir (most recently created) must exist while
+        # the "conversion" runs, separate from the outer working tmp_dir.
+        assert created_profile_dirs[-1].exists()
+        outdir = Path(args[args.index("--outdir") + 1])
+        (outdir / "input.docx").write_bytes(b"PK\x03\x04")
+        return MagicMock(returncode=0)
+
+    monkeypatch.setattr(drawingml_utils.subprocess, "run", fake_run)
+
+    result = drawingml_utils.convert_to_modern_format(
+        BytesIO(b"legacy doc bytes"), "doc", "docx", timeout_s=5
+    )
+
+    assert isinstance(result, BytesIO)
+    assert captured_kwargs["timeout"] == 5
+
+    # Both the outer working directory and the isolated profile directory
+    # are cleaned up once the conversion completes.
+    assert not created_profile_dirs[0].exists()
+    assert not created_profile_dirs[-1].exists()
