{"record":{"id":"21b479e321b74d9e","repo":"docling-project/docling","slug":"libreoffice-is-required-to-convert-a-source-suff","errorCode":null,"errorMessage":"LibreOffice is required to convert a .{source_suffix} file to .{target_suffix}. Install LibreOffice and make sure it is on PATH.","messagePattern":"LibreOffice is required to convert a \\.(.+?) file to \\.(.+?)\\. Install LibreOffice and make sure it is on PATH\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/docx/drawingml/utils.py","lineNumber":112,"sourceCode":"        source: Path to the source file, or a ``BytesIO`` with its contents.\n        source_suffix: File extension of the source format without leading dot\n            (e.g. ``\"doc\"``, ``\"xls\"``, ``\"ppt\"``).  Required when *source* is\n            a ``BytesIO`` so the temp file gets the right name; ignored for\n            ``Path`` inputs (the path's own suffix is used instead).\n        target_suffix: Target extension without leading dot (``\"docx\"``,\n            ``\"xlsx\"``, or ``\"pptx\"``).\n        timeout_s: Timeout in seconds for the LibreOffice subprocess.\n\n    Returns:\n        A ``BytesIO`` buffer with the converted file contents.\n\n    Raises:\n        RuntimeError: When LibreOffice is not installed, the subprocess fails,\n            or the expected output file is not produced.\n    \"\"\"\n    libreoffice_cmd = get_libreoffice_cmd()\n    if libreoffice_cmd is None:\n        raise RuntimeError(\n            f\"LibreOffice is required to convert a .{source_suffix} file to \"\n            f\".{target_suffix}. Install LibreOffice and make sure it is on PATH.\"\n        )\n\n    tmp_dir = Path(mkdtemp())\n    try:\n        if isinstance(source, BytesIO):\n            source.seek(0)\n            input_path = tmp_dir / f\"input.{source_suffix}\"\n            input_path.write_bytes(source.read())\n        else:\n            input_path = source\n\n        with _isolated_libreoffice_profile() as profile_arg:\n            subprocess.run(\n                [\n                    libreoffice_cmd,\n                    profile_arg,","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/docx/drawingml/utils.py#L94-L130","documentation":"The convert_with_soffice helper in docling.backend.docx.drawingml.utils raises this RuntimeError when it needs to run a LibreOffice conversion (e.g. docx->pdf or pptx->pdf to rasterize DrawingML/shape content) but get_libreoffice_cmd() returned None. It names the exact source and target suffixes involved and tells you to install LibreOffice and put it on PATH. Unlike error 11 this check is passive (no smoke test) — it fires before any subprocess is spawned.","triggerScenarios":"Converting DOCX (or XLSX/PPTX) files that contain drawings/shapes/images requiring rasterization, on a host without libreoffice/soffice discoverable via PATH or the default macOS app path. The suffixes in the message tell you which conversion stage needed it (commonly source docx, target pdf).","commonSituations":"Same environments as the 'Libreoffice not found' error: slim containers, minimal CI images, servers without an office suite. Files with embedded charts, SmartArt, or shape-heavy headers trigger the LibreOffice path, so the same pipeline works for plain DOCX but fails on drawing-rich ones.","solutions":["Install LibreOffice and ensure soffice is on PATH (apt-get install -y libreoffice / brew install --cask libreoffice); verify with soffice --version in the same shell/environment that runs docling.","In containers, bake LibreOffice into the image rather than installing at runtime.","If you cannot install LibreOffice, preprocess files to strip drawings, or accept degraded output by disabling the drawing-conversion feature if the calling option allows it.","Confirm the binary name: some distros ship only 'libreoffice' or only 'soffice'; symlink if needed (ln -s /usr/bin/libreoffice /usr/local/bin/soffice)."],"exampleFix":"# before\n$ python -c \"from docling.document_converter import DocumentConverter; DocumentConverter().convert('chart_report.docx')\"\nRuntimeError: LibreOffice is required to convert a .docx file to .pdf.\n\n# after\n$ sudo apt-get update && sudo apt-get install -y libreoffice\n$ soffice --version  # verify discoverable\n$ python -c \"from docling.document_converter import DocumentConverter; DocumentConverter().convert('chart_report.docx')\"","handlingStrategy":"validation","validationCode":"import shutil, os\n\ndef soffice_on_path() -> bool:\n    return (shutil.which(\"libreoffice\") is not None\n            or shutil.which(\"soffice\") is not None\n            or os.path.isfile(\"/Applications/LibreOffice.app/Contents/MacOS/soffice\"))\n\n# gate the feature before converting drawing-heavy files\nassert soffice_on_path(), \"LibreOffice required for DrawingML rasterization\"","typeGuard":null,"tryCatchPattern":"try:\n    result = conv.convert(docx_path)\nexcept RuntimeError as e:\n    if \"LibreOffice is required\" in str(e):\n        install_or_skip(docx_path)  # env problem: fix image/host, not the file\n    else:\n        raise","preventionTips":["Install LibreOffice in slim containers when processing Office files with charts/shapes.","Check the exact suffixes in the message to identify which conversion stage needed LibreOffice.","Keep an environment probe (shutil.which) in deployment smoke tests."],"tags":["libreoffice","environment","dependency","docx","conversion"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}