{"record":{"id":"87f91a6fee4be76a","repo":"infiniflow/ragflow","slug":"docx-generation-failed-str-e","errorCode":null,"errorMessage":"DOCX generation failed: {str(e)}","messagePattern":"DOCX generation failed: (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"agent/component/docs_generator.py","lineNumber":627,"sourceCode":"            finally:\n                if os.path.exists(header_path):\n                    os.remove(header_path)\n            return self._apply_pdf_overlay(file_path)\n        except Exception as e:\n            raise Exception(f\"PDF generation failed: {str(e)}\")\n\n    def _generate_docx(self, content: str) -> tuple[str, bytes]:\n        try:\n            file_path, _ = self._generate_pandoc_binary_output(\n                content,\n                \"docx\",\n                \"docx\",\n                include_timestamp_in_body=False,\n                extra_args=[\"--standalone\"],\n            )\n            return self._decorate_docx(file_path)\n        except Exception as e:\n            raise Exception(f\"DOCX generation failed: {str(e)}\")\n\n    def _generate_txt(self, content: str) -> tuple[str, bytes]:\n        try:\n            return self._generate_pandoc_text_output(content, \"plain\", \"txt\")\n        except Exception as e:\n            raise Exception(f\"TXT generation failed: {str(e)}\")\n\n    def _generate_markdown(self, content: str) -> tuple[str, bytes]:\n        try:\n            return self._generate_pandoc_text_output(content, \"markdown\", \"md\")\n        except Exception as e:\n            raise Exception(f\"Markdown generation failed: {str(e)}\")\n\n    def _generate_html(self, content: str) -> tuple[str, bytes]:\n        try:\n            return self._generate_pandoc_text_output(content, \"html\", \"html\")\n        except Exception as e:\n            raise Exception(f\"HTML generation failed: {str(e)}\")","sourceCodeStart":609,"sourceCodeEnd":645,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/component/docs_generator.py#L609-L645","documentation":"Catch-all wrapper thrown by DocGenerator._generate_docx (agent/component/docs_generator.py): any exception from the pandoc docx conversion or the subsequent _decorate_docx step is re-raised as Exception('DOCX generation failed: <inner message>'). The decorated DOCX path adds headers/footers, so failures can come from either pandoc or the python-docx decoration logic.","triggerScenarios":"Running DocGenerator with output_format 'docx' when pandoc is missing/broken (pypandoc OSError), the markdown cannot be converted, or _decorate_docx fails (e.g. python-docx template/style errors, corrupted intermediate file). The try wraps both the pandoc call and the decoration.","commonSituations":"Environments where pypandoc cannot find the pandoc binary; version drift between pandoc and pypandoc; documents with structures pandoc's docx writer rejects; transient temp-file issues in the output directory.","solutions":["Read the suffix after 'DOCX generation failed:' to identify the true failing step","Ensure pandoc is installed and discoverable (pandoc --version); install pypandoc_binary if no system pandoc","Test the content directly: pandoc content.md -o out.docx --standalone","If decoration is the failure, check temp-dir writability (TMPDIR) and python-docx availability in the worker environment"],"exampleFix":"# environment fix\npip install pypandoc-binary   # bundles pandoc when system pandoc is absent","handlingStrategy":"try-catch","validationCode":"import shutil\n\ndef docx_prerequisites_ok():\n    return shutil.which('pandoc') is not None or pypandoc_is_binary_install()","typeGuard":null,"tryCatchPattern":"try:\n    file_path, file_bytes = generator._generate_docx(content)\nexcept Exception as e:\n    inner = str(e).removeprefix('DOCX generation failed: ')\n    logger.error('DOCX generation root cause: %s', inner)\n    if 'No pandoc was found' in inner:\n        raise RuntimeError('Install pandoc or pip install pypandoc-binary') from e\n    raise","preventionTips":["Read the inner exception text, not the wrapper headline","Install pandoc or pypandoc-binary in every environment running DocGenerator","Ensure TMPDIR is writable for the intermediate docx decoration step","Test pandoc docx conversion directly when diagnosing"],"tags":["doc-generator","docx","pandoc","runtime","error-wrapping"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}