infiniflow/ragflow · error · Exception

DOCX generation failed: {str(e)}

Error message

DOCX generation failed: {str(e)}

What it means

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.

Source

Thrown at agent/component/docs_generator.py:627

            finally:
                if os.path.exists(header_path):
                    os.remove(header_path)
            return self._apply_pdf_overlay(file_path)
        except Exception as e:
            raise Exception(f"PDF generation failed: {str(e)}")

    def _generate_docx(self, content: str) -> tuple[str, bytes]:
        try:
            file_path, _ = self._generate_pandoc_binary_output(
                content,
                "docx",
                "docx",
                include_timestamp_in_body=False,
                extra_args=["--standalone"],
            )
            return self._decorate_docx(file_path)
        except Exception as e:
            raise Exception(f"DOCX generation failed: {str(e)}")

    def _generate_txt(self, content: str) -> tuple[str, bytes]:
        try:
            return self._generate_pandoc_text_output(content, "plain", "txt")
        except Exception as e:
            raise Exception(f"TXT generation failed: {str(e)}")

    def _generate_markdown(self, content: str) -> tuple[str, bytes]:
        try:
            return self._generate_pandoc_text_output(content, "markdown", "md")
        except Exception as e:
            raise Exception(f"Markdown generation failed: {str(e)}")

    def _generate_html(self, content: str) -> tuple[str, bytes]:
        try:
            return self._generate_pandoc_text_output(content, "html", "html")
        except Exception as e:
            raise Exception(f"HTML generation failed: {str(e)}")

View on GitHub (pinned to 554fb1133a)

Solutions

  1. Read the suffix after 'DOCX generation failed:' to identify the true failing step
  2. Ensure pandoc is installed and discoverable (pandoc --version); install pypandoc_binary if no system pandoc
  3. Test the content directly: pandoc content.md -o out.docx --standalone
  4. If decoration is the failure, check temp-dir writability (TMPDIR) and python-docx availability in the worker environment

Example fix

# environment fix
pip install pypandoc-binary   # bundles pandoc when system pandoc is absent
Defensive patterns

Strategy: try-catch

Validate before calling

import shutil

def docx_prerequisites_ok():
    return shutil.which('pandoc') is not None or pypandoc_is_binary_install()

Try / catch

try:
    file_path, file_bytes = generator._generate_docx(content)
except Exception as e:
    inner = str(e).removeprefix('DOCX generation failed: ')
    logger.error('DOCX generation root cause: %s', inner)
    if 'No pandoc was found' in inner:
        raise RuntimeError('Install pandoc or pip install pypandoc-binary') from e
    raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/87f91a6fee4be76a. Report an issue: GitHub.