jeecgboot/JeecgBoot · error · JeecgBootBizTipException

result.getMessage()

Error message

result.getMessage()

What it means

This error is thrown when airagKnowledgeDocService.editDocument() returns a non-success Result (result.isSuccess() is false). The thrown message is whatever the service layer set in result.getMessage(), which could be any business-level failure message from the document editing pipeline (e.g. embedding failure, vector store error, content too large). This is the AI knowledge base document write failure path.

Source

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

    @Autowired
    private IAiragKnowledgeDocService airagKnowledgeDocService;

    @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

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Check the server logs for the specific error message from editDocument — the thrown exception message contains the Result.message which has the root cause.
2. Verify the vector database (pgvector) is running and accessible.
3. Validate that the embedding model API key and endpoint are correctly configured in the AI model settings.
4. Confirm the knowledgeId exists and is active in the system.
5. If the content is very large, try splitting it into smaller documents or configuring a different segmentation strategy.

Example fix

// before — no visibility into the service failure
Result<?> result = airagKnowledgeDocService.editDocument(knowledgeDoc);
if (!result.isSuccess()) {
    throw new JeecgBootBizTipException(result.getMessage());
}

// after — log the detailed failure for diagnostics
Result<?> result = airagKnowledgeDocService.editDocument(knowledgeDoc);
if (!result.isSuccess()) {
    log.error("[AI-KNOWLEDGE] editDocument failed for knowledgeId={}, message={}", knowledgeId, result.getMessage());
    throw new JeecgBootBizTipException(result.getMessage());
}

// Before calling knowledgeWriteTextDocument, validate preconditions
if (knowledgeId == null || knowledgeId.isEmpty()) {
    throw new IllegalArgumentException("knowledgeId is required");
}
if (content == null || content.isEmpty()) {
    throw new IllegalArgumentException("content is required");
}
// Check vector DB connectivity
// (implementation-specific health check) 

// Check if the knowledge base exists and is accessible
public static boolean isKnowledgeBaseReady(IAiragKnowledgeDocService service, String knowledgeId) {
    try {
        long count = service.count(new LambdaQueryWrapper<AiragKnowledgeDoc>()
            .eq(AiragKnowledgeDoc::getKnowledgeId, knowledgeId));
        return count >= 0; // query succeeded = DB is reachable
    } catch (Exception e) {
        return false;
    }
}

try {
    String docId = airagBaseApi.knowledgeWriteTextDocument(knowledgeId, title, content, segmentConfig);
    return docId;
} catch (JeecgBootBizTipException e) {
    log.error("Failed to write knowledge document: knowledgeId={}, error={}", knowledgeId, e.getMessage());
    // Inspect e.getMessage() for the specific service-level failure
    throw e;
}

When it happens

Trigger: A call to IAiragBaseApi.knowledgeWriteTextDocument() with a valid knowledgeId and non-empty content, where the underlying editDocument service operation fails. The service returns Result.fail() or Result.error() with a message describing the specific failure (e.g. knowledge not found, embedding API timeout, vector database connection error, document content exceeds limits).

Common situations: The vector database (pgvector/Milvus) is down or unreachable. The embedding model API key is invalid or expired. The knowledge base ID references a deleted or non-existent knowledge base. The document content exceeds the embedding model's token limit. Database connectivity issues.

Related errors

• 知识库文档ID为空
• 调用大模型接口失败:
• 当前系统未配置默认图像模型，请前往yml中配置默认模型
• 请先添加变量或者记忆后再次重试！
• 文件路径包含非法字符

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