{"record":{"id":"029c81776546a719","repo":"apache/incubator-seata","slug":"mcp-put-call-tc-failed","errorCode":null,"errorMessage":"MCP PUT Call TC Failed.","messagePattern":"MCP PUT Call TC Failed\\.","errorType":"exception","errorClass":"ServiceCallException","httpStatus":null,"severity":"error","filePath":"console/src/main/java/org/apache/seata/mcp/service/impl/ConsoleRemoteServiceImpl.java","lineNumber":247,"sourceCode":"        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    }\n\n    private String readResponseBody(RestClient.RequestHeadersSpec.ConvertibleClientHttpResponse response)\n            throws IOException {\n        return response.getBody() == null ? \"\" : StreamUtils.copyToString(response.getBody(), StandardCharsets.UTF_8);\n    }\n}","sourceCodeStart":229,"sourceCodeEnd":265,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/console/src/main/java/org/apache/seata/mcp/service/impl/ConsoleRemoteServiceImpl.java#L229-L265","documentation":"Thrown when the RestTemplate/RestClient PUT call from the Seata console MCP service to the TC fails at the transport level (RestClientException): connection refused, DNS failure, connect/read timeout, or TLS problems. It is distinct from error 120, which covers a completed HTTP exchange with a bad status; here the exchange never completed.","triggerScenarios":"executing an MCP tool that triggers executeRequest(url, PUT, entity) while the TC host is down, the configured hostname does not resolve, a firewall drops the connection, the connect/read timeout is exceeded, or an HTTPS endpoint presents an untrusted certificate.","commonSituations":"TC process stopped or crashed, console started before TC in docker-compose (race at startup), wrong host/port in console config, network policy blocking the console->TC path, or self-signed TLS on TC without the CA in the console truststore.","solutions":["Confirm the TC process is up: check port listening (e.g. ss -ltnp | grep <tc-port>) and TC health endpoint.","Fix connectivity: correct host/port in the console MCP remote configuration, open firewall/security-group rules, fix DNS.","If timeouts, raise the console HTTP client read/connect timeout settings to cover slow TC operations.","For HTTPS failures, import the TC certificate into the console JVM truststore instead of disabling verification."],"exampleFix":"// before: TC not started / wrong host\nString url = \"http://wrong-host:7091/api/v1/...\";\n// after: verified reachable TC endpoint\nString url = \"http://tc-host:7091/api/v1/...\";","handlingStrategy":"retry","validationCode":"// preflight: resolve + connect to TC before issuing PUT\nInetSocketAddress a = new InetSocketAddress(host, port);\nif (a.isUnresolved()) throw new IllegalStateException(\"TC host unresolved: \" + host);\ntry (Socket s = new Socket()) { s.connect(a, 2000); }","typeGuard":null,"tryCatchPattern":"catch (ServiceCallException e) {\n    Throwable cause = e.getCause(); // RestClientException\n    if (cause instanceof ConnectException) { /* wait for TC, then retry */ }\n    else if (cause instanceof ResourceAccessException && cause.getCause() instanceof SocketTimeoutException) { raiseTimeout(); }\n    else { escalate; }\n}","preventionTips":["Start TC before console in orchestrators (depends_on with healthcheck)","Set explicit connect/read timeouts so failures are fast, not hung","Monitor TC availability from the console host continuously"],"tags":["network","mcp","console","connection-refused","timeout"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}