iflytek/astron-agent · error · BusinessException

REPO_KNOWLEDGE_ADD_FAILED

REPO_KNOWLEDGE_ADD_FAILED

Error message

ResponseEnum.REPO_KNOWLEDGE_ADD_FAILED

What it means

KnowledgeService adds a knowledge point (chunk) by delegating to knowledgeV2ServiceCallHandler.saveChunk(request), the upstream RAG/knowledge service call. If that service returns a response with code != 0, the method logs the upstream message and throws BusinessException(REPO_KNOWLEDGE_ADD_FAILED). This wraps any downstream failure of the chunk-save operation.

Solutions

1. Read the logged 'Failed to add knowledge point, message:{}' line — it carries the upstream error message and points to the real cause.
2. Verify the ragflowDatasetId is set and valid for the file's source (check repo.getRagflowDatasetId()).
3. Confirm the upstream knowledge/RAGFlow service is healthy and its API contract matches the request fields (ragType, chunks, docId).
4. Retry the add once the upstream service recovers; if content-related, reduce chunk size or sanitize the text.

Example fix

// before
response = knowledgeV2ServiceCallHandler.saveChunk(request); // code!=0 -> REPO_KNOWLEDGE_ADD_FAILED

// after
response = knowledgeV2ServiceCallHandler.saveChunk(request);
if (response.getCode() != 0) {
    log.error("saveChunk failed docId={} ragType={} msg={}", request.getDocId(), request.getRagType(), response.getMessage());
    // inspect response.getMessage() to fix datasetId/ragType/payload before retrying
}

if (repo.getRagflowDatasetId() == null) {
    throw new BusinessException(ResponseEnum.REPO_DATASET_NOT_READY); // avoid doomed saveChunk call
}

try {
    knowledgeService.addKnowledgePoint(request);
} catch (BusinessException e) {
    if (ResponseEnum.REPO_KNOWLEDGE_ADD_FAILED.getCode().equals(e.getCode())) {
        // inspect upstream message in logs; verify datasetId/ragType; retry with backoff
    } else { throw e; }
}

When it happens

Trigger: saveChunk is called with a chunk payload the upstream knowledge/RAGFlow service rejects: invalid or missing ragflowDatasetId, unsupported ragType/source, oversized chunk content, upstream service unavailable returning a non-zero error code, or a doc that no longer exists upstream.

Common situations: Dataset ID not yet created in RAGFlow (applyRagflowDatasetId produced null); upstream RAG service restarted or degraded; chunk text exceeding upstream size limits; version drift between console backend and knowledge service API contract.

Related errors

• REPO_CREATE_RAGFLOW_FAILED
• REPO_KNOWLEDGE_MODIFY_FAILED
• REPO_FILE_DELETE_FAILED
• REPO_KNOWLEDGE_DELETE_FAILED
• RESPONSE_FAILED

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/2516aa83ed7bc66f. Report an issue: GitHub.

Appendix: source

Thrown at console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/repo/KnowledgeService.java:1487

     * @param addChunkArray JSON array containing chunks to be added
     * @param source the source type of the knowledge base (AIUI/CBG)
     * @return KnowledgeResponse containing the operation result
     * @throws BusinessException if knowledge addition fails
     */
    private KnowledgeResponse addKnowledge(String docId, String group, String datasetId,
            JSONArray addChunkArray, String source) {
        KnowledgeResponse response = new KnowledgeResponse();
        if (!addChunkArray.isEmpty()) { // Embedding
            KnowledgeRequest request = new KnowledgeRequest();
            request.setDocId(docId);
            request.setGroup(group);
            applyRagflowDatasetId(request, source, datasetId);
            request.setChunks(addChunkArray.toArray());
            request.setRagType(source);
            response = knowledgeV2ServiceCallHandler.saveChunk(request);
            if (response.getCode() != 0) {
                log.error("Failed to add knowledge point, message:{}", response.getMessage());
                throw new BusinessException(ResponseEnum.REPO_KNOWLEDGE_ADD_FAILED);
            }
        }
        return response;
    }

    /**
     * Add knowledge chunks specifically for CBG knowledge base
     *
     * @param docId the document ID
     * @param group the group/repository ID
     * @param addChunkArray JSON array containing chunks to be added
     * @param source the source type (should be CBG)
     * @return Map containing dataIndex to knowledge ID mapping
     * @throws BusinessException if CBG knowledge base operations fail
     */
    public Map<String, String> addKnowledge4CBG(String docId, String group, JSONArray addChunkArray, String source) {
        return addKnowledge4CBG(docId, group, null, addChunkArray, source);
    }

View on GitHub (pinned to 5e758547a8)