[Bug]: Word (.docx) parsing fails in Title Chunker with "NoneType + str" error / [ERROR]expected string or bytes-like object, got 'NoneType'

[Sandrine-lll]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (Language Policy).
• Non-english title submitions will be closed directly ( 非英文标题的提交将会被直接关闭 ) (Language Policy).
• Please do not modify this template :) and fill in all the required fields.

RAGFlow workspace code commit ID

20260305

RAGFlow image version

v0.24.0

Other environment information

Deployment: Docker
OS: v0.24.0
RAGFlow: Latest version
Browser: Chrome

Actual behavior

When using RAGFlow pipeline to parse a Word (.docx) document, the pipeline fails at the Title Chunker stage.

The Parser step finishes successfully, but the Title Chunker throws the following error:

unsupported operand type(s) for +: 'NoneType' and 'str'

Full log:

[File]:
10:30:15: File fetched.
10:30:15: Done
Start the pipeline...

[Parser]:
10:30:15: Start to work on a Word Processor Document
10:30:17: Done

[Title Chunker]:
10:30:17: Start to merge hierarchically.
10:30:17: unsupported operand type(s) for +: 'NoneType' and 'str'
10:30:17: [ERROR]unsupported operand type(s) for +: 'NoneType' and 'str'

The pipeline structure is:

File → Parser (Word) → Title Chunker → Embedding

Expected behavior

Word (.docx) documents should be parsed successfully through the pipeline, including the Title Chunker stage, similar to PDF, TXT, or Markdown files.

Steps to reproduce

When using RAGFlow pipeline to parse a Word (.docx) document, the pipeline fails at the Title Chunker stage.

The Parser step finishes successfully, but the Title Chunker throws the following error:

unsupported operand type(s) for +: 'NoneType' and 'str'

Full log:

[File]:
10:30:15: File fetched.
10:30:15: Done
Start the pipeline...
---------------------------------------
[Parser]:
10:30:15: Start to work on a Word Processor Document
10:30:17: Done
---------------------------------------
[Title Chunker]:
10:30:17: Start to merge hierarchically.
10:30:17: unsupported operand type(s) for +: 'NoneType' and 'str'
10:30:17: [ERROR]unsupported operand type(s) for +: 'NoneType' and 'str'

The pipeline structure is:

File → Parser (Word) → Title Chunker → Embedding

Additional information

标题模版.json

[Sandrine-lll]

Additional observation:

The same pipeline configuration works correctly when parsing TXT and PDF files.

Pipeline:
File → Parser → Title Chunker → Embedding

Results:

• TXT file: parsed successfully

• PDF file: parsed successfully

• DOCX file: fails at the Title Chunker stage with the error

  unsupported operand type(s) for +: 'NoneType' and 'str'

If the same DOCX document is converted to Markdown (.md), the pipeline also works correctly.

This suggests the issue may be related specifically to the Word (.docx) parser output, which might contain None values that are not handled properly during hierarchical title merging.

[dosubot]

Hi @Sandrine-lll! I'm Dosu and I’m helping the ragflow team.

Your observation is spot on. The issue is indeed specific to the DOCX parser output.

The root cause appears to be in rag/app/manual.py where the Title Chunker's DOCX processing performs "\n".join(question_stack) without checking if elements are None. When the DOCX parser encounters empty paragraphs, it can produce None values that get appended to question_stack, causing the join operation to fail.

Why DOCX differs from PDF/TXT:

• The DOCX parser preserves style information as (text, style) tuples and can append empty results for paragraphs without text content
• TXT parser returns a simple [[text, ""]] structure without style tracking
• Interestingly, the HierarchicalMerger component has explicit None handling that converts None to empty strings, but the Title Chunker's DOCX processing path bypasses this protection

Workaround: Converting to Markdown first (as you discovered) works because the Markdown structure doesn't preserve these empty paragraph artifacts.

This looks like a legitimate bug where null-safety checks are missing in the DOCX-specific Title Chunker code path.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[Sandrine-lll]

Thanks for the analysis.

However, in previous versions of RAGFlow, the same DOCX files could be successfully parsed using the same pipeline configuration.

The issue only appeared after upgrading to the latest version.

Therefore it seems that this might be a regression related to the DOCX parser or the Title Chunker logic.

In our production workflow we prefer not to convert DOCX files to Markdown before ingestion, because this introduces an additional transformation step that may slightly modify the original text structure and increase the risk of parsing inconsistencies.

Is there any recommended workaround to handle DOCX files directly in the pipeline without converting them to Markdown?

Or is there any configuration option that could avoid the None value issue in the Title Chunker?

Thanks for your help.

[dosubot]

You're likely right that this is a regression. There have been several recent fixes related to DOCX parsing NoneType issues:

• PR #12965 (Feb 3, 2026): Fixed ValueError: too many values to unpack and added NoneType guards
• PR #12822 (Jan 26, 2026): Fixed parent chunking failure for DOCX files
• PR #12993: Documents that some NoneType entries from DOCX table blocks can still crash the HierarchicalMerger

Workarounds without converting to Markdown:

1. Use the Naive Chunker instead of Title Chunker - it's the most stable DOCX-compatible alternative and uses successive text slicing without the hierarchical merging that's causing the NoneType issue

2. Other DOCX-compatible chunkers: Book, QA, Manual, Laws, and One chunkers all support DOCX format and may work depending on your document structure

3. If Title Chunker is required: Does your document contain tables? Tables with empty cells are a known source of None values. If you can remove or simplify tables in your source documents, that may help.

Given that this worked in previous versions, this does appear to be a regression that should be fixed. The workaround of using Naive Chunker is likely your best option for production until the Title Chunker's DOCX handling is fixed.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[Magicbook1108]

This issue has been fixed in recent pull request. Pull the latest code and try again.

[Sandrine-lll]

Thanks for the update.

I pulled the latest code and redeployed RAGFlow, but unfortunately the same error still occurs when parsing DOCX files in the pipeline. The error message remains:

unsupported operand type(s) for +: 'NoneType'

The pipeline configuration is the same as before:

File → Parser (Word) → Title Chunker → Embedding

For comparison:

• TXT files work correctly
• PDF files work correctly
• DOCX files still fail at the Title Chunker stage

It seems the issue might still occur in some DOCX parsing scenarios.

Could you please help confirm a few things:

1. Which commit or release includes the fix for this issue?
2. Are there any additional steps required after pulling the latest code (e.g., rebuilding specific services or clearing caches)?
3. Is there a recommended configuration or workaround for handling DOCX files directly without converting them to Markdown?

Thanks for your help!

[Magicbook1108]

1. Please take a screenshot of your git log.
2. Are you running RAGFlow from Docker or from source? If you are running from docker, you may need to pull the nightly version.
3. Please share the .docx file with me. I will test it on my side to confirm whether the issue still persists.

[Sandrine-lll]

2.通过 Docker 运行

测试缩减版.docx

[Magicbook1108]

Pull nightly. I am running well with your document.