apache/incubator-seata · error · FrameworkException

Watch request failed with code %d: %s

Error message

Watch request failed with code %d: %s

What it means

Thrown by SeataHttpWatch.createWatch when the watch HTTP request completes with a non-successful status code. The framework formats the response code and the drained response body into the message so the caller can see why the server refused the watch (e.g. 404 unknown path, 401 bad credentials, 500 server error).

Source

Thrown at common/src/main/java/org/apache/seata/common/util/SeataHttpWatch.java:107

     * @param eventType the class type for deserializing event data
     * @param <T>       the event data type
     * @return a Watch instance
     * @throws IOException if the request fails
     */
    public static <T> SeataHttpWatch<T> createWatch(Call call, Class<T> eventType) throws IOException {

        okhttp3.Response response = call.execute();

        if (!response.isSuccessful()) {
            String respBody = null;
            try (ResponseBody body = response.body()) {
                if (body != null) {
                    respBody = body.string();
                }
            } catch (IOException e) {
                throw new FrameworkException(e, "Watch request failed: " + response.message());
            }
            throw new FrameworkException(
                    String.format("Watch request failed with code %d: %s", response.code(), respBody));
        }

        // Verify Content-Type is event stream
        String contentType = response.header("Content-Type");
        if (contentType == null || !contentType.contains("text/event-stream")) {
            LOGGER.warn("Expected Content-Type: text/event-stream, got: {}", contentType);
        }

        return new SeataHttpWatch<>(response.body(), call, eventType);
    }

    /**
     * Create a Watch instance with a prepared request
     *
     * @param client    the OkHttpClient instance
     * @param request   the HTTP request
     * @param eventType the class type for deserializing event data

View on GitHub (pinned to e01f97c6db)

Solutions

  1. Read the embedded code and body in the message — they state the server's exact complaint.
  2. For 401/403: fix username/password or token configuration for the Seata server.
  3. For 404: correct the watch endpoint URL/path to match the deployed Seata server version.
  4. For 5xx: inspect server-side logs; restart or fix the server, then re-create the watch.

Example fix

// before
SeataHttpWatch<MyEvent> watch = SeataHttpWatch.createWatch(call, MyEvent.class);

// after
try {
    watch = SeataHttpWatch.createWatch(call, MyEvent.class);
} catch (FrameworkException e) {
    // message contains 'Watch request failed with code <code>: <body>'
    log.error("watch rejected: {}", e.getMessage());
    throw e;
}
Defensive patterns

Strategy: try-catch

Try / catch

try {
    watch = SeataHttpWatch.createWatch(call, eventType);
} catch (FrameworkException e) {
    String msg = String.valueOf(e.getMessage());
    if (msg.contains("code 401") || msg.contains("code 403")) {
        refreshCredentials();
    } else if (msg.contains("code 404")) {
        throw new ConfigurationException("wrong watch endpoint URL", e);
    } else {
        scheduleReconnectWithBackoff();
    }
}

Prevention

When it happens

Trigger: call.execute() returns any non-2xx status: wrong URL/path for the watch endpoint, missing or invalid auth credentials (401/403), unknown resource/group (404), or server-side failure (500). The body string is included verbatim in the message.

Common situations: Misconfigured seata.service watch endpoint in registry config; Seata server version mismatch where the watch API path changed; token/vhost gating rejecting the client; pointing the client at a non-watch port (e.g. console port instead of the API port).

Related errors

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