jeecgboot/JeecgBoot · error · JeecgBootBizTipException

知识库文档ID为空

Error message

知识库文档ID为空

What it means

This error is thrown when airagKnowledgeDocService.editDocument() succeeds (returns a success Result) but the knowledgeDoc object's ID remains null after the operation. This indicates the service accepted the document but did not assign or populate an ID, which is an internal consistency failure. The caller (knowledgeWriteTextDocument) needs the ID to return it.

Source

Thrown at jeecg-boot/jeecg-boot-module/jeecg-boot-module-airag/src/main/java/org/jeecg/modules/airag/api/AiragBaseApiImpl.java:51

    @Override
    public String knowledgeWriteTextDocument(String knowledgeId, String title, String content, String segmentConfig) {
        AssertUtils.assertNotEmpty("知识库ID不能为空", knowledgeId);
        AssertUtils.assertNotEmpty("写入内容不能为空", content);
        AiragKnowledgeDoc knowledgeDoc = new AiragKnowledgeDoc();
        knowledgeDoc.setKnowledgeId(knowledgeId);
        knowledgeDoc.setTitle(title);
        knowledgeDoc.setType(LLMConsts.KNOWLEDGE_DOC_TYPE_TEXT);
        knowledgeDoc.setContent(content);
        // 将分段策略配置写入文档的metadata中，EmbeddingHandler会从中读取分段配置
        if (oConvertUtils.isNotEmpty(segmentConfig)) {
            knowledgeDoc.setMetadata(segmentConfig);
        }
        Result<?> result = airagKnowledgeDocService.editDocument(knowledgeDoc);
        if (!result.isSuccess()) {
            throw new JeecgBootBizTipException(result.getMessage());
        }
        if (knowledgeDoc.getId() == null) {
            throw new JeecgBootBizTipException("知识库文档ID为空");
        }
        log.info("[AI-KNOWLEDGE] 文档写入完成，知识库:{}, 文档ID:{}", knowledgeId, knowledgeDoc.getId());
        return knowledgeDoc.getId();
    }

    @Autowired
    private IAiragAppService airagAppService;

    @Autowired
    private IAiragVariableService airagVariableService;

    @Autowired
    private IAiragPromptsService airagPromptsService;

    @Override
    public String getChatVariable(String appId, String username, String name) {
        return airagVariableService.getVariable(username, appId, name);
    }

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Check the AiragKnowledgeDoc entity's @TableId annotation and ensure IdType is correctly configured.
2. Verify the Snowflake/ID generation worker configuration is valid (worker ID within range, datacenter ID within range).
3. Debug the editDocument service implementation to confirm the ID is set on the entity after insert.
4. Check database logs to see if the insert actually succeeded and what ID was generated.

Example fix

// before — relying on the passed-in object to have its ID populated
Result<?> result = airagKnowledgeDocService.editDocument(knowledgeDoc);
if (knowledgeDoc.getId() == null) {
    throw new JeecgBootBizTipException("知识库文档ID为空");
}

// after — query back for the document to obtain the ID
Result<?> result = airagKnowledgeDocService.editDocument(knowledgeDoc);
if (knowledgeDoc.getId() == null && result.getResult() instanceof AiragKnowledgeDoc) {
    knowledgeDoc.setId(((AiragKnowledgeDoc) result.getResult()).getId());
}
if (knowledgeDoc.getId() == null) {
    throw new JeecgBootBizTipException("知识库文档ID为空");
}

// Before relying on the returned ID, verify the service populated it
AiragKnowledgeDoc doc = new AiragKnowledgeDoc();
doc.setKnowledgeId(knowledgeId);
// ... set fields
Result<?> result = service.editDocument(doc);
if (result.isSuccess() && doc.getId() == null) {
    // Query back using knowledge ID + title to find the created document
    log.warn("editDocument succeeded but ID is null; attempting recovery query");
}

public static boolean hasValidId(AiragKnowledgeDoc doc) {
    return doc != null && doc.getId() != null && !doc.getId().isEmpty();
}

try {
    String docId = airagBaseApi.knowledgeWriteTextDocument(knowledgeId, title, content, segmentConfig);
    return docId;
} catch (JeecgBootBizTipException e) {
    if ("知识库文档ID为空".equals(e.getMessage())) {
        // Document was created but ID wasn't returned — investigate service impl
        log.error("ID population failed after successful editDocument for knowledgeId={}", knowledgeId);
    }
    throw e;
}

When it happens

Trigger: A call to knowledgeWriteTextDocument() where editDocument returns success but does not set the ID on the knowledgeDoc entity. This can happen if the service implementation uses a different entity instance internally, if the ID generation strategy fails, or if the insert/update logic has a bug that doesn't populate the generated key back.

Common situations: MyBatis-Plus ID generation strategy (IdType.ASSIGN_ID) fails due to Snowflake worker configuration issues. The service implementation creates a new entity internally and doesn't copy the ID back. A database insert succeeded but the generated key wasn't returned due to JDBC driver behavior. The entity's @TableId annotation is misconfigured.

Related errors

• result.getMessage()
• 用户不存在!
• 请先添加变量或者记忆后再次重试！
• 调用大模型接口失败:
• 文件路径包含非法字符

AI-assisted analysis of jeecgboot/JeecgBoot@96fb33f5ec (2026-08-14). Data as JSON: /api/errors/e4523e4c408a022f. Report an issue: GitHub.