What causes "Markdown generation failed: {str(e)}" in infiniflow/ragflow?

Read the appended inner message to get the root cause

infiniflow/ragflow · error · Exception

Markdown generation failed: {str(e)}

Error message

Markdown generation failed: {str(e)}

What it means

Catch-all wrapper thrown by DocGenerator._generate_markdown (agent/component/docs_generator.py): the pandoc markdown->markdown round-trip (used to normalize the content, strip templates, add a timestamp) raised and is re-raised as Exception('Markdown generation failed: <inner message>'). The inner exception carries the actual cause, typically pandoc availability or parse errors.

Source

Thrown at agent/component/docs_generator.py:639

                "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

Read the appended inner message to get the root cause
Install pandoc (apt-get install pandoc) or pip install pypandoc-binary so the conversion can run
Ensure TMPDIR is writable and large enough for the output
Pre-validate the content is non-empty valid UTF-8 markdown

Example fix

# environment fix
sudo apt-get install -y pandoc   # Debian/Ubuntu; verify with: pandoc --version

Defensive patterns

Strategy: try-catch

Validate before calling

import shutil

def markdown_prerequisites_ok():
    return shutil.which('pandoc') is not None

Try / catch

try:
    file_path, file_bytes = generator._generate_markdown(content)
except Exception as e:
    inner = str(e).removeprefix('Markdown generation failed: ')
    logger.error('Markdown generation root cause: %s', inner)
    raise

Prevention

Ensure pandoc is installed in the worker environment, not just locally
Pre-validate content encoding before feeding the generator
Watch pandoc extension behavior when upgrading versions

When it happens

Trigger: Running DocGenerator with output_format 'markdown' when pandoc is missing (pypandoc OSError), input content has constructs the markdown reader rejects, or the temp output write fails. Raised from the except around _generate_pandoc_text_output(content, 'markdown', 'md').

Common situations: Same class as TXT: missing pandoc binary in the runtime environment; content with mixed/invalid encodings; pandoc version changes to extension handling; read-only temp directories.

Related errors

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