{"record":{"id":"2516aa83ed7bc66f","repo":"iflytek/astron-agent","slug":"repo-knowledge-add-failed","errorCode":"REPO_KNOWLEDGE_ADD_FAILED","errorMessage":"ResponseEnum.REPO_KNOWLEDGE_ADD_FAILED","messagePattern":"ResponseEnum\\.REPO_KNOWLEDGE_ADD_FAILED","errorType":"error_code","errorClass":"BusinessException","httpStatus":null,"severity":"error","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/repo/KnowledgeService.java","lineNumber":1487,"sourceCode":"     * @param addChunkArray JSON array containing chunks to be added\n     * @param source the source type of the knowledge base (AIUI/CBG)\n     * @return KnowledgeResponse containing the operation result\n     * @throws BusinessException if knowledge addition fails\n     */\n    private KnowledgeResponse addKnowledge(String docId, String group, String datasetId,\n            JSONArray addChunkArray, String source) {\n        KnowledgeResponse response = new KnowledgeResponse();\n        if (!addChunkArray.isEmpty()) { // Embedding\n            KnowledgeRequest request = new KnowledgeRequest();\n            request.setDocId(docId);\n            request.setGroup(group);\n            applyRagflowDatasetId(request, source, datasetId);\n            request.setChunks(addChunkArray.toArray());\n            request.setRagType(source);\n            response = knowledgeV2ServiceCallHandler.saveChunk(request);\n            if (response.getCode() != 0) {\n                log.error(\"Failed to add knowledge point, message:{}\", response.getMessage());\n                throw new BusinessException(ResponseEnum.REPO_KNOWLEDGE_ADD_FAILED);\n            }\n        }\n        return response;\n    }\n\n    /**\n     * Add knowledge chunks specifically for CBG knowledge base\n     *\n     * @param docId the document ID\n     * @param group the group/repository ID\n     * @param addChunkArray JSON array containing chunks to be added\n     * @param source the source type (should be CBG)\n     * @return Map containing dataIndex to knowledge ID mapping\n     * @throws BusinessException if CBG knowledge base operations fail\n     */\n    public Map<String, String> addKnowledge4CBG(String docId, String group, JSONArray addChunkArray, String source) {\n        return addKnowledge4CBG(docId, group, null, addChunkArray, source);\n    }","sourceCodeStart":1469,"sourceCodeEnd":1505,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/repo/KnowledgeService.java#L1469-L1505","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the logged 'Failed to add knowledge point, message:{}' line — it carries the upstream error message and points to the real cause.","Verify the ragflowDatasetId is set and valid for the file's source (check repo.getRagflowDatasetId()).","Confirm the upstream knowledge/RAGFlow service is healthy and its API contract matches the request fields (ragType, chunks, docId).","Retry the add once the upstream service recovers; if content-related, reduce chunk size or sanitize the text."],"exampleFix":"// before\nresponse = knowledgeV2ServiceCallHandler.saveChunk(request); // code!=0 -> REPO_KNOWLEDGE_ADD_FAILED\n\n// after\nresponse = knowledgeV2ServiceCallHandler.saveChunk(request);\nif (response.getCode() != 0) {\n    log.error(\"saveChunk failed docId={} ragType={} msg={}\", request.getDocId(), request.getRagType(), response.getMessage());\n    // inspect response.getMessage() to fix datasetId/ragType/payload before retrying\n}","handlingStrategy":"try-catch","validationCode":"if (repo.getRagflowDatasetId() == null) {\n    throw new BusinessException(ResponseEnum.REPO_DATASET_NOT_READY); // avoid doomed saveChunk call\n}","typeGuard":null,"tryCatchPattern":"try {\n    knowledgeService.addKnowledgePoint(request);\n} catch (BusinessException e) {\n    if (ResponseEnum.REPO_KNOWLEDGE_ADD_FAILED.getCode().equals(e.getCode())) {\n        // inspect upstream message in logs; verify datasetId/ragType; retry with backoff\n    } else { throw e; }\n}","preventionTips":["Always check the upstream response message in logs before changing code.","Ensure ragflowDatasetId is created before chunk saves.","Keep chunk content within upstream size limits.","Retry transient upstream failures with exponential backoff."],"tags":["java","ragflow","upstream-error","knowledge-base"],"backgroundTag":"upstream-api-error","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}