{"record":{"id":"59c828b61ace3e7b","repo":"apache/incubator-seata","slug":"watch-request-failed-with-code-d-s","errorCode":null,"errorMessage":"Watch request failed with code %d: %s","messagePattern":"Watch request failed with code (.+?): (.+?)","errorType":"exception","errorClass":"FrameworkException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/org/apache/seata/common/util/SeataHttpWatch.java","lineNumber":107,"sourceCode":" * @param eventType the class type for deserializing event data\n * @param the event data type\n * @return a Watch instance\n * @throws IOException if the request fails\n */\n public static SeataHttpWatch createWatch(Call call, Class 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\n * @param request the HTTP request\n * @param eventType the class type for deserializing event data","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/common/src/main/java/org/apache/seata/common/util/SeataHttpWatch.java#L89-L125","documentation":"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).","triggerScenarios":"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.","commonSituations":"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).","solutions":["Read the embedded code and body in the message — they state the server's exact complaint.","For 401/403: fix username/password or token configuration for the Seata server.","For 404: correct the watch endpoint URL/path to match the deployed Seata server version.","For 5xx: inspect server-side logs; restart or fix the server, then re-create the watch."],"exampleFix":"// before\nSeataHttpWatch watch = SeataHttpWatch.createWatch(call, MyEvent.class);\n\n// after\ntry {\n watch = SeataHttpWatch.createWatch(call, MyEvent.class);\n} catch (FrameworkException e) {\n // message contains 'Watch request failed with code

: '\n    log.error(\"watch rejected: {}\", e.getMessage());\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    watch = SeataHttpWatch.createWatch(call, eventType);\n} catch (FrameworkException e) {\n    String msg = String.valueOf(e.getMessage());\n    if (msg.contains(\"code 401\") || msg.contains(\"code 403\")) {\n        refreshCredentials();\n    } else if (msg.contains(\"code 404\")) {\n        throw new ConfigurationException(\"wrong watch endpoint URL\", e);\n    } else {\n        scheduleReconnectWithBackoff();\n    }\n}","preventionTips":["Validate the watch URL and credentials in config before first use.","Surface the embedded code and body from the message — it names the exact server complaint.","Alert on repeated 5xx watch failures rather than silently looping."],"tags":["http","watch","auth","configuration","seata-server"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}