{"record":{"id":"2050533813dd2dfa","repo":"iflytek/astron-agent","slug":"response-failed-message","errorCode":"RESPONSE_FAILED","errorMessage":"${message}","messagePattern":"\\$\\{message\\}","errorType":"error_code","errorClass":"BusinessException","httpStatus":null,"severity":"error","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/handler/McpServerHandler.java","lineNumber":174,"sourceCode":"        }\n    }\n\n    /**\n     * Debug tool\n     *\n     * @param req\n     */\n    public JSONObject debugServerTool(JSONObject req) {\n        try {\n            String url = apiUrl.getToolUrl() + MCP_SERVER_CALL_TOOL;\n            log.info(\"Mcp tool call url:{}\\ndata:{}\", url, JSON.toJSONString(req));\n            String resp = OkHttpUtil.post(url, req.toString());\n            JSONObject respObject = JSON.parseObject(resp);\n            log.info(\"Mcp tool call response data:{}\", resp);\n            if (respObject.getIntValue(\"code\") == 0) {\n                return respObject.getJSONObject(\"data\");\n            }\n            throw new BusinessException(ResponseEnum.RESPONSE_FAILED, respObject.getString(\"message\"));\n        } catch (Exception e) {\n            log.info(\"Mcp tool call error\");\n            throw new BusinessException(ResponseEnum.FAILED_TOOL_CALL);\n        }\n    }\n\n    public JSONObject getMcpServerInfo(String serverId) {\n        try {\n            String url = apiUrl.getMcpToolServer() + MCP_SERVER_INFO + \"?mcp_server_id=\" + URLEncoder.encode(serverId, StandardCharsets.UTF_8.name());\n\n            log.info(\"Mcp server info url:{}\\ndata:{}\", url, serverId);\n            String resp = OkHttpUtil.get(url);\n            JSONObject respObject = JSON.parseObject(resp);\n            log.info(\"Mcp server info response data:{}\", resp);\n            if (respObject.getIntValue(\"code\") == 0) {\n                return respObject.getJSONObject(\"data\");\n            }\n            throw new BusinessException(ResponseEnum.FAILED_MCP_GET_DETAIL);","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/handler/McpServerHandler.java#L156-L192","documentation":"debugServerTool invokes an MCP server tool over HTTP; when the response JSON has code != 0 it propagates the downstream 'message' verbatim in a BusinessException(RESPONSE_FAILED). This means the MCP tool call reached the server but the server reported an error.","triggerScenarios":"HTTP POST to the MCP tool-call endpoint returns JSON with non-zero code (e.g. tool not found on the server, invalid tool arguments, tool execution failure).","commonSituations":"Debugging a tool whose arguments don't match the server schema; MCP server registered but the tool was removed/renamed; server-side execution error in the tool implementation.","solutions":["Read the propagated downstream message — it is the MCP server's own error text","Validate tool arguments against the tool's declared input schema before calling","Confirm the tool name still exists on the MCP server (re-fetch the tool list)","Check the MCP server logs for the failing tool execution"],"exampleFix":"// before\nthrow new BusinessException(ResponseEnum.RESPONSE_FAILED, respObject.getString(\"message\"));\n// after\nString detail = respObject.getString(\"message\");\nlog.error(\"Mcp tool call rejected: code={}, message={}\", respObject.getIntValue(\"code\"), detail);\nthrow new BusinessException(ResponseEnum.RESPONSE_FAILED, detail);","handlingStrategy":"try-catch","validationCode":"// validate tool args against the tool's schema before debugServerTool\nboolean valid = jsonSchemaValidator.validate(toolInputSchema, args);\nif (!valid) throw new IllegalArgumentException(\"tool args do not match schema\");","typeGuard":null,"tryCatchPattern":"try {\n    JSONObject result = mcpServerHandler.debugServerTool(req);\n} catch (BusinessException e) {\n    // message is the MCP server's own error text; show it to the debugger\n    log.warn(\"tool call failed: {}\", e.getMessage());\n}","preventionTips":["Re-fetch the tool list before debugging to confirm tool existence","Validate arguments against the tool's declared input schema","Distinguish downstream errors (code!=0) from transport errors (FAILED_TOOL_CALL) when handling"],"tags":["http","mcp","java","tool-call","downstream-error"],"backgroundTag":"api-error-response","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"}