{"record":{"id":"6d479dcef1d960dd","repo":"iflytek/astron-agent","slug":"repo-knowledge-query-failed","errorCode":"REPO_KNOWLEDGE_QUERY_FAILED","errorMessage":"ResponseEnum.REPO_KNOWLEDGE_QUERY_FAILED","messagePattern":"ResponseEnum\\.REPO_KNOWLEDGE_QUERY_FAILED","errorType":"error_code","errorClass":"BusinessException","httpStatus":null,"severity":"error","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/repo/RepoService.java","lineNumber":787,"sourceCode":"        }\n        boolean hasEnabledFile = false;\n        for (FileDirectoryTree fileDirectoryTree : fileDirectoryTrees) {\n            FileInfoV2 fileInfoV2 = fileInfoV2Service.getById(fileDirectoryTree.getFileId());\n            if (fileInfoV2 != null && fileInfoV2.getEnabled() == 1) {\n                hasEnabledFile = true;\n                break;\n            }\n        }\n        if (!hasEnabledFile) {\n            throw new BusinessException(ResponseEnum.REPO_FILE_DISABLED);\n        }\n\n        QueryRequest request = this.getKnowledgeQueryObject(repo, topN, query);\n\n        KnowledgeResponse resp = knowledgeV2ServiceCallHandler.knowledgeQuery(request);\n        if (resp.getCode() != 0) {\n            log.error(\"Knowledge retrieval failed, message:{}\", resp.getMessage());\n            throw new BusinessException(ResponseEnum.REPO_KNOWLEDGE_QUERY_FAILED);\n        }\n\n        HitTestHistory hitTestHistory = new HitTestHistory();\n        hitTestHistory.setRepoId(id);\n        hitTestHistory.setUserId(UserInfoManagerHandler.getUserId());\n        hitTestHistory.setQuery(query);\n        hitTestHistory.setCreateTime(new Timestamp(System.currentTimeMillis()));\n        historyService.save(hitTestHistory);\n\n        QueryRespData data = JSON.parseObject(resp.getData().toString(), QueryRespData.class);\n        List<ChunkInfo> results = data.getResults();\n        Map<Long, FileDirectoryTree> processedFileIds = new HashMap<>();\n        if (!CollectionUtils.isEmpty(results)) {\n            for (ChunkInfo info : results) {\n                String docId = info.getDocId();\n                FileInfoV2 fileInfoV2 = fileInfoV2Service.getOnly(new QueryWrapper<FileInfoV2>().eq(\"uuid\", docId));\n                // Skip if this fileId has already been processed\n                if (!processedFileIds.containsKey(fileInfoV2.getId())) {","sourceCodeStart":769,"sourceCodeEnd":805,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/repo/RepoService.java#L769-L805","documentation":"RepoService.hitTest calls knowledgeV2ServiceCallHandler.knowledgeQuery(request); if the returned KnowledgeResponse code != 0 it logs the upstream message and throws REPO_KNOWLEDGE_QUERY_FAILED. This is a wrapper around a failure of the downstream knowledge retrieval microservice, not a problem with the repo record itself.","triggerScenarios":"The knowledge core service returns a non-zero code — vector DB unavailable, embedding model error, malformed query, retrieval timeout, or core service internal error.","commonSituations":"Knowledge service not deployed or unreachable after a partial deployment; index/collection missing because documents never finished vectorizing; oversized topN or query text rejected by the retrieval engine.","solutions":["Read the server log line 'Knowledge retrieval failed, message:{}' for the upstream cause","Verify the knowledge service is running and reachable (registration/config of knowledgeV2ServiceCallHandler target)","Confirm the repo's documents completed vectorization and the underlying collection exists","Retry with a smaller topN / shorter query to rule out payload-related rejections; then escalate to the knowledge service team with the logged message"],"exampleFix":"// before\nKnowledgeResponse resp = handler.knowledgeQuery(request);\nif (resp.getCode() != 0) { throw new BusinessException(ResponseEnum.REPO_KNOWLEDGE_QUERY_FAILED); }\n// after\nKnowledgeResponse resp = handler.knowledgeQuery(request);\nif (resp.getCode() != 0) {\n    log.error(\"Knowledge retrieval failed, message:{}, repoId:{}\", resp.getMessage(), repo.getId());\n    throw new BusinessException(ResponseEnum.REPO_KNOWLEDGE_QUERY_FAILED);\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    repoService.hitTest(repoId, query, topN, true);\n} catch (BusinessException e) {\n    if (\"REPO_KNOWLEDGE_QUERY_FAILED\".equals(e.getCode())) {\n        // check knowledge service health, then retry with backoff\n    }\n}","preventionTips":["Monitor knowledge service availability before running retrieval tests","Ensure documents finished vectorizing before querying","Bound topN and query length to known-safe values","Retry transient failures with exponential backoff; alert on persistent non-zero codes"],"tags":["knowledge-base","retrieval","upstream-service"],"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-19T12:17:13.211Z"}