{"record":{"id":"4d498c38fafa2bcb","repo":"apache/incubator-seata","slug":"mcp-put-request-returned-non-success-status-s-r","errorCode":null,"errorMessage":"MCP PUT request returned non-success status: %s, response: %s","messagePattern":"MCP PUT request returned non-success status: (.+?), response: (.+?)","errorType":"exception","errorClass":"ServiceCallException","httpStatus":null,"severity":"error","filePath":"console/src/main/java/org/apache/seata/mcp/service/impl/ConsoleRemoteServiceImpl.java","lineNumber":241,"sourceCode":"        } else {\n            setNamespaceHeaderAndQueryParam(nameSpaceDetail, headers, queryParams);\n        }\n        headers.add(WebSecurityConfig.AUTHORIZATION_HEADER, getToken());\n        Map<String, Object> queryParamsMap = objectToQueryParamMap(objectQueryParams, objectMapper);\n        String url = buildUrl(namingServerProperties.getNamingServerUrl(), path, queryParams, queryParamsMap);\n        HttpEntity<String> entity = new HttpEntity<>(headers);\n        String responseBody;\n        try {\n            ResponseEntity<String> response = executeRequest(url, HttpMethod.PUT, entity);\n\n            responseBody = response.getBody();\n\n            if (!response.getStatusCode().is2xxSuccessful()) {\n                String errorMsg = String.format(\n                        \"MCP PUT request returned non-success status: %s, response: %s\",\n                        response.getStatusCode(), response.getBody());\n                LOGGER.warn(errorMsg);\n                throw new ServiceCallException(errorMsg, response.getStatusCode());\n            }\n            return responseBody;\n        } catch (RestClientException e) {\n            String errorMsg = \"MCP PUT Call TC Failed.\";\n            LOGGER.error(errorMsg, e);\n            throw new ServiceCallException(errorMsg);\n        }\n    }\n\n    private ResponseEntity<String> executeRequest(String url, HttpMethod httpMethod, HttpEntity<String> entity)\n            throws RestClientException {\n        return restClient\n                .method(Objects.requireNonNull(httpMethod))\n                .uri(Objects.requireNonNull(url))\n                .headers(headers -> headers.addAll(entity.getHeaders()))\n                .exchange((request, response) -> new ResponseEntity<>(\n                        readResponseBody(response), response.getHeaders(), response.getStatusCode()));\n    }","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/console/src/main/java/org/apache/seata/mcp/service/impl/ConsoleRemoteServiceImpl.java#L223-L259","documentation":"Thrown by the Seata console MCP service when an HTTP PUT forwarded to the Transaction Coordinator (TC) completes with a non-2xx status. The console MCP module acts as an HTTP client proxying tool calls (e.g. forced transaction/lock modifications) to the TC's HTTP endpoint; any non-success status is wrapped in a ServiceCallException together with the HTTP status code and response body.","triggerScenarios":"Calling an MCP console tool that mutates TC state (update/delete global transaction, remove lock) while the TC HTTP endpoint rejects the request: 404 from a wrong console-to-TC URL path, 401/403 when the auth token in the headers is missing or expired, 500 when TC fails to apply the operation, or 503 when TC is starting up.","commonSituations":"Misconfigured console-to-TC address (console.session.transport-to-tc URL), missing or stale TC auth token, TC version older than the console so the REST route does not exist, or the TC overloaded returning 5xx during a large transaction load.","solutions":["Verify the TC server is running and its HTTP port is reachable from the console host (curl the same PUT URL manually).","Check the console configuration for the TC base URL and context path; fix scheme/host/port/path mismatches.","Inspect the response body embedded in the message: 401/403 means fix the Authorization header/token; 404 means wrong path or TC version; 5xx means check TC server logs for the root cause.","If TC was mid-restart or overloaded, retry the operation once TC reports healthy."],"exampleFix":"// before: point at wrong port\nconsole.remote.tc.url=http://tc-host:8091\n// after: correct console-to-TC http endpoint\nconsole.remote.tc.url=http://tc-host:7091/api/v1","handlingStrategy":"try-catch","validationCode":"// verify TC endpoint reachable and token present before the tool call\nURI u = URI.create(tcUrl);\ntry (Socket s = new Socket()) {\n    s.connect(new InetSocketAddress(u.getHost(), u.getPort()), 2000);\n}\nAssert.hasText(authToken, \"TC auth token missing\");","typeGuard":null,"tryCatchPattern":"try {\n    String body = consoleRemoteService.httpPut(url, headers);\n} catch (ServiceCallException e) {\n    HttpStatus st = (HttpStatus) e.getStatusCode(); // 120 carries the status; 121 does not\n    if (st.is4xxClientError()) { /* fix url/token, do not blind-retry */ }\n    else { backoffAndRetryOnce(); }\n}","preventionTips":["Health-check the TC HTTP endpoint before exposing MCP modify tools","Keep console and TC on matched versions so REST paths exist","Alert on 5xx rate from the console->TC hop"],"tags":["http","mcp","console","tc-server","status-code"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}