jeecgboot/JeecgBoot · error · JeecgBootException
请先上传文件
Error message
请先上传文件
What it means
Thrown by EmbeddingHandler.parseFile() when the document metadata JSON does not contain the KNOWLEDGE_DOC_METADATA_FILEPATH key. The method also checks for null/empty metadata via AssertUtils before this, so this specific throw means metadata exists and is valid JSON but lacks the file path field — indicating the document was created without an associated uploaded file.
Source
Thrown at jeecg-boot/jeecg-boot-module/jeecg-boot-module-airag/src/main/java/org/jeecg/modules/airag/llm/handler/EmbeddingHandler.java:804
} catch (Exception e) {
log.error("网页解析失败, URL: {}, 错误: {}", website, e.getMessage(), e);
throw new JeecgBootException("网页解析失败: " + e.getMessage());
}
}
/**
* 解析文件
*
* @param doc
* @author chenrui
* @date 2025/3/5 11:31
*/
private String parseFile(AiragKnowledgeDoc doc) {
String metadata = doc.getMetadata();
AssertUtils.assertNotEmpty("请先上传文件", metadata);
JSONObject metadataJson = JSONObject.parseObject(metadata);
if (!metadataJson.containsKey(LLMConsts.KNOWLEDGE_DOC_METADATA_FILEPATH)) {
throw new JeecgBootException("请先上传文件");
}
String filePath = metadataJson.getString(LLMConsts.KNOWLEDGE_DOC_METADATA_FILEPATH);
AssertUtils.assertNotEmpty("请先上传文件", filePath);
// 网络资源,先下载到临时目录
filePath = ensureFile(filePath);
// 提取文档内容
File docFile = new File(filePath);
if (docFile.exists()) {
Document document = new TikaDocumentParser(AutoDetectParser::new, null, null, null).parse(docFile);
if (null != document) {
String content = document.text();
// 判断是否md文档
String fileType = FilenameUtils.getExtension(docFile.getName());
if ("md".contains(fileType)) {
// 如果是md文件，查找所有图片语法，如果是本地图片，替换成网络图片
String baseUrl = "#{domainURL}/sys/common/static/";
String sourcePath = metadataJson.getString(LLMConsts.KNOWLEDGE_DOC_METADATA_SOURCES_PATH);
if(oConvertUtils.isNotEmpty(sourcePath)) {View on GitHub (pinned to 96fb33f5ec)
Solutions
- Re-upload the file for this knowledge-base document to populate the filePath metadata.
- Check the document record in the database to verify the metadata JSON structure.
- If records are created programmatically, ensure filePath is set in the metadata before the document is activated.
Defensive patterns
Strategy: validation
Validate before calling
JSONObject meta = JSONObject.parseObject(doc.getMetadata());
if (meta == null || !meta.containsKey(LLMConsts.KNOWLEDGE_DOC_METADATA_FILEPATH)) {
throw new JeecgBootException("请先上传文件后再执行此操作");
} Type guard
private static boolean hasFilePath(AiragKnowledgeDoc doc) {
if (doc == null || doc.getMetadata() == null) return false;
JSONObject meta = JSONObject.parseObject(doc.getMetadata());
return meta != null
&& meta.containsKey(LLMConsts.KNOWLEDGE_DOC_METADATA_FILEPATH)
&& oConvertUtils.isNotEmpty(meta.getString(LLMConsts.KNOWLEDGE_DOC_METADATA_FILEPATH));
} Prevention
- Ensure documents are only activated after the file upload step completes successfully.
- Validate metadata integrity when creating or updating document records.
- Add a database constraint or application-level check to prevent documents without filePath from being processed.
When it happens
Trigger: A knowledge-base document record exists in the database but its metadata JSON is missing the 'filePath' key. This happens when the document record was inserted without completing the file upload step, or when the metadata was corrupted/overwritten without the path.
Common situations: Document record was created programmatically without going through the upload flow; a database migration or update cleared the filePath; the user started creating a document but the upload failed silently leaving a partial record.
Related errors
AI-assisted analysis of jeecgboot/JeecgBoot@96fb33f5ec (2026-08-14).
Data as JSON: /api/errors/905174b684da9d30.
Report an issue: GitHub.