[Question]:Cannot process scanned PDF in Knowledge Base - "Skipped empty document" error

[Colada-K]

Do you need to ask a question?

• I have searched the existing questions and discussions and this question is not already answered.
• I believe this is a legitimate question, not just a bug or feature request.

Your Question

Problem

When uploading a scanned PDF (image-based, no text layer) to the Knowledge Base,
the initialization fails with the following error:

Skipped empty document: xxx.pdf
No valid documents found
RAG pipeline returned failure

Steps to reproduce

1. Upload a scanned PDF to Knowledge Base
2. Initialization starts but fails immediately

My setup

• DeepTutor version: v1.3.3
• OS: Windows
• LLM: DeepSeek
• Embedding: Jina

Question

I installed magic-pdf hoping it would enable OCR for scanned PDFs,
but the error persists.

Is there a way to enable MinerU/magic-pdf for scanned PDF processing
in the current v1.x architecture? If so, how should it be configured?

Thank you!

Related Module

Knowledge Base Management

Additional Context

No response

[pancacake]

Hi, could you please check if there's some pip library missing?

[pancacake]

I've encountered this before and tunrs out the reason is I forgot to activate the env lol

[Colada-K]

Thanks for the quick response!

After investigating further, I found the actual root cause: document_loader.py only uses PyMuPDF's get_text() to extract text, which returns empty for scanned/image-based PDFs. There's no OCR fallback, so the document gets skipped entirely.

Installing magic-pdf alone doesn't help since the code never calls it for scanned PDFs.

I haven't been able to resolve this on my end yet. Would the team consider adding an OCR fallback (e.g. EasyOCR or magic-pdf) for scanned PDFs in a future release? This would make DeepTutor much more useful for users working with textbook scans.

[pancacake]

Thanks for the quick response!

After investigating further, I found the actual root cause: document_loader.py only uses PyMuPDF's get_text() to extract text, which returns empty for scanned/image-based PDFs. There's no OCR fallback, so the document gets skipped entirely.

Installing magic-pdf alone doesn't help since the code never calls it for scanned PDFs.

I haven't been able to resolve this on my end yet. Would the team consider adding an OCR fallback (e.g. EasyOCR or magic-pdf) for scanned PDFs in a future release? This would make DeepTutor much more useful for users working with textbook scans.

thanks for the advice! We'll see what we can we can do!

[pancacake]

https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.6 feel free to try this~

[norrybul]

I've been following this project and not had enough time yet with the knowledgebase. I hope to see options to use other document processing models (paddleocr, mineru...) and reranker models too with custom chunking. It will be a blast. But defaults are perfect with the right choices, especially the search apis which varies from user preference of search results. I had to use a a back-end proxy for Google Search API (for SearXNG). Great app!