From 207eb34ba20fe021dfdb942cd197e14bfb9a7eaa Mon Sep 17 00:00:00 2001
From: Ruochen Pan <sorainygreen@gmail.com>
Date: Tue, 14 Apr 2026 16:44:14 +0800
Subject: [PATCH] fix: improve error handling for knowledge base upload (#7536)

* fix: improve error handling for knowledge base upload

- Log details field in KnowledgeBaseUploadError for better debugging
- Distinguish between empty pre-chunked text and empty chunking result
  with appropriate error messages

* style: format code
---
 astrbot/core/knowledge_base/kb_helper.py | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/astrbot/core/knowledge_base/kb_helper.py b/astrbot/core/knowledge_base/kb_helper.py
index 601a2425f..fab080ea0 100644
--- a/astrbot/core/knowledge_base/kb_helper.py
+++ b/astrbot/core/knowledge_base/kb_helper.py
@@ -329,11 +329,20 @@ class KBHelper:
                     ) from exc
 
             if not chunks_text or not any(chunk.strip() for chunk in chunks_text):
-                raise KnowledgeBaseUploadError(
-                    stage="chunking",
-                    user_message=("分块失败：文档内容为空，未生成任何可索引文本块。"),
-                    details={"file_name": file_name},
-                )
+                if pre_chunked_text is not None:
+                    raise KnowledgeBaseUploadError(
+                        stage="validation",
+                        user_message=("预分块文本为空，未提供任何可索引文本块。"),
+                        details={"file_name": file_name},
+                    )
+                else:
+                    raise KnowledgeBaseUploadError(
+                        stage="chunking",
+                        user_message=(
+                            "分块失败：文档内容为空，未生成任何可索引文本块。"
+                        ),
+                        details={"file_name": file_name},
+                    )
 
             contents = []
             metadatas = []
@@ -423,7 +432,7 @@ class KBHelper:
             return doc
         except Exception as e:
             if isinstance(e, KnowledgeBaseUploadError):
-                logger.warning(f"上传文档失败: {e}")
+                logger.warning(f"上传文档失败: {e}", extra={"details": e.details})
             else:
                 logger.error(f"上传文档失败: {e}", exc_info=True)
             # if file_path.exists():