apache/incubator-seata · error · ServiceCallException

MCP PUT request returned non-success status: %s, response: %

Error message

MCP PUT request returned non-success status: %s, response: %s

What it means

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.

Source

Thrown at console/src/main/java/org/apache/seata/mcp/service/impl/ConsoleRemoteServiceImpl.java:241

        } else {
            setNamespaceHeaderAndQueryParam(nameSpaceDetail, headers, queryParams);
        }
        headers.add(WebSecurityConfig.AUTHORIZATION_HEADER, getToken());
        Map<String, Object> queryParamsMap = objectToQueryParamMap(objectQueryParams, objectMapper);
        String url = buildUrl(namingServerProperties.getNamingServerUrl(), path, queryParams, queryParamsMap);
        HttpEntity<String> entity = new HttpEntity<>(headers);
        String responseBody;
        try {
            ResponseEntity<String> response = executeRequest(url, HttpMethod.PUT, entity);

            responseBody = response.getBody();

            if (!response.getStatusCode().is2xxSuccessful()) {
                String errorMsg = String.format(
                        "MCP PUT request returned non-success status: %s, response: %s",
                        response.getStatusCode(), response.getBody());
                LOGGER.warn(errorMsg);
                throw new ServiceCallException(errorMsg, response.getStatusCode());
            }
            return responseBody;
        } catch (RestClientException e) {
            String errorMsg = "MCP PUT Call TC Failed.";
            LOGGER.error(errorMsg, e);
            throw new ServiceCallException(errorMsg);
        }
    }

    private ResponseEntity<String> executeRequest(String url, HttpMethod httpMethod, HttpEntity<String> entity)
            throws RestClientException {
        return restClient
                .method(Objects.requireNonNull(httpMethod))
                .uri(Objects.requireNonNull(url))
                .headers(headers -> headers.addAll(entity.getHeaders()))
                .exchange((request, response) -> new ResponseEntity<>(
                        readResponseBody(response), response.getHeaders(), response.getStatusCode()));
    }

View on GitHub (pinned to e01f97c6db)

Solutions

  1. Verify the TC server is running and its HTTP port is reachable from the console host (curl the same PUT URL manually).
  2. Check the console configuration for the TC base URL and context path; fix scheme/host/port/path mismatches.
  3. 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.
  4. If TC was mid-restart or overloaded, retry the operation once TC reports healthy.

Example fix

// before: point at wrong port
console.remote.tc.url=http://tc-host:8091
// after: correct console-to-TC http endpoint
console.remote.tc.url=http://tc-host:7091/api/v1
Defensive patterns

Strategy: try-catch

Validate before calling

// verify TC endpoint reachable and token present before the tool call
URI u = URI.create(tcUrl);
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(u.getHost(), u.getPort()), 2000);
}
Assert.hasText(authToken, "TC auth token missing");

Try / catch

try {
    String body = consoleRemoteService.httpPut(url, headers);
} catch (ServiceCallException e) {
    HttpStatus st = (HttpStatus) e.getStatusCode(); // 120 carries the status; 121 does not
    if (st.is4xxClientError()) { /* fix url/token, do not blind-retry */ }
    else { backoffAndRetryOnce(); }
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/4d498c38fafa2bcb. Report an issue: GitHub.