{"record":{"id":"7099c5e37678c866","repo":"apache/incubator-seata","slug":"watch-request-failed","errorCode":null,"errorMessage":"Watch request failed: {}","messagePattern":"Watch request failed: (.+?)","errorType":"exception","errorClass":"FrameworkException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/org/apache/seata/common/util/SeataHttpWatch.java","lineNumber":105,"sourceCode":"     *\n     * @param call      the prepared HTTP call\n     * @param eventType the class type for deserializing event data\n     * @param <T>       the event data type\n     * @return a Watch instance\n     * @throws IOException if the request fails\n     */\n    public static <T> SeataHttpWatch<T> createWatch(Call call, Class<T> eventType) throws IOException {\n\n        okhttp3.Response response = call.execute();\n\n        if (!response.isSuccessful()) {\n            String respBody = null;\n            try (ResponseBody body = response.body()) {\n                if (body != null) {\n                    respBody = body.string();\n                }\n            } catch (IOException e) {\n                throw new FrameworkException(e, \"Watch request failed: \" + response.message());\n            }\n            throw new FrameworkException(\n                    String.format(\"Watch request failed with code %d: %s\", response.code(), respBody));\n        }\n\n        // Verify Content-Type is event stream\n        String contentType = response.header(\"Content-Type\");\n        if (contentType == null || !contentType.contains(\"text/event-stream\")) {\n            LOGGER.warn(\"Expected Content-Type: text/event-stream, got: {}\", contentType);\n        }\n\n        return new SeataHttpWatch<>(response.body(), call, eventType);\n    }\n\n    /**\n     * Create a Watch instance with a prepared request\n     *\n     * @param client    the OkHttpClient instance","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/common/src/main/java/org/apache/seata/common/util/SeataHttpWatch.java#L87-L123","documentation":"Thrown by SeataHttpWatch.createWatch when the OkHttp call executing a watch (long-poll/SSE) request fails while reading the error response body. The server returned a non-success HTTP status, and additionally the attempt to drain the body to include it in the diagnostic message raised an IOException, so the original failure is wrapped in a FrameworkException with the status-line message only.","triggerScenarios":"Calling createWatch(call, eventType) where call.execute() returns a non-2xx response (e.g. 401/403/404/500 from the server) and reading response.body().string() itself fails — typically because the connection was reset mid-body or the body stream was already closed/expired.","commonSituations":"Seata server (http://host:port) is up enough to answer with an error but drops the connection while streaming the error body; auth token rejected with a truncated body; proxies/load balancers (nginx, istio) closing errored responses early; server restarting during the watch handshake.","solutions":["Check Seata server health and logs: the non-2xx status is the root cause; the IOException here only masks the body.","Verify the watch URL, port and any auth headers on the OkHttp Call before calling createWatch.","If a proxy sits between client and server, raise its proxy_read_timeout / disable buffering for text/event-stream endpoints.","Retry the watch creation with backoff — a transient 5xx plus reset should succeed on a later attempt."],"exampleFix":"// before\nSeataHttpWatch<MyEvent> watch = SeataHttpWatch.createWatch(call, MyEvent.class);\n\n// after: validate the endpoint is healthy first, and wrap transient failures\nokhttp3.Response probe = probeCall.execute();\nif (!probe.isSuccessful()) {\n    throw new IllegalStateException(\"watch endpoint unhealthy: \" + probe.code());\n}\nprobe.close();\nSeataHttpWatch<MyEvent> watch;\ntry {\n    watch = SeataHttpWatch.createWatch(call, MyEvent.class);\n} catch (FrameworkException e) {\n    // log code + message, schedule reconnect with backoff\n    throw e;\n}","handlingStrategy":"retry","validationCode":"okhttp3.Request probe = call.request().newBuilder().head().build();\ntry (okhttp3.Response r = client.newCall(probe).execute()) {\n    if (!r.isSuccessful()) {\n        throw new IllegalStateException(\"watch endpoint returned \" + r.code());\n    }\n}","typeGuard":null,"tryCatchPattern":"catch (FrameworkException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Watch request failed\")) {\n        scheduleReconnectWithBackoff();\n    } else {\n        throw e;\n    }\n}","preventionTips":["Health-check the watch endpoint before establishing a long-lived watch.","Build OkHttp clients with retryOnConnectionFailure(true).","Keep server and client on compatible releases so error paths stay well-formed."],"tags":["network","http","watch","okhttp","seata-server"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}