{"record":{"id":"80ead39e155242d8","repo":"SonarSource/sonarqube","slug":"error-while-executing-graphql-query-return-code","errorCode":null,"errorMessage":"Error while executing GraphQl query. Return code %s. Error message: %s.","messagePattern":"Error while executing GraphQl query\\. Return code (.+?)\\. Error message: (.+?)\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"server/sonar-server-common/src/main/java/org/sonar/server/common/graphql/GraphQlClient.java","lineNumber":134,"sourceCode":"  private <T> GsonGraphQlAnswer<T> fetchValidDataOrThrow(\n    String graphQlApiUrl,\n    String accessToken,\n    Type answerDataType,\n    GsonGraphQlQuery paginatedQuery\n  ) throws IOException {\n    RequestBody body = RequestBody.create(GSON.toJson(paginatedQuery), MediaType.parse(\"application/json; charset=utf-8\"));\n    Request request = new Request.Builder()\n      .url(graphQlApiUrl)\n      .post(body)\n      .addHeader(\"Authorization\", \"Bearer \" + accessToken)\n      .build();\n    return executeCallAndDeserializeAnswer(answerDataType, request);\n  }\n\n  private <T> @NotNull GsonGraphQlAnswer<T> executeCallAndDeserializeAnswer(Type answerDataType, Request request) throws IOException {\n    try (Response response = client.newCall(request).execute()) {\n      if (!response.isSuccessful()) {\n        throw new IllegalStateException(format(\"Error while executing GraphQl query. Return code %s. Error message: %s.\", response.code(), response.body().string()));\n      }\n      return deserializeValidAnswerOrThrow(answerDataType, response);\n    }\n  }\n\n  private static <T> GsonGraphQlAnswer<T> deserializeValidAnswerOrThrow(Type answerDataType, Response response) {\n    GsonGraphQlAnswer<T> graphQlAnswer;\n    Function<String, GsonGraphQlAnswer<T>> toObject = stringPayload -> GSON.fromJson(stringPayload, answerDataType);\n    Optional<String> bodyString = Optional.empty();\n    try {\n      bodyString = Optional.ofNullable(response.body()).map(body -> {\n        try {\n          return body.string();\n        } catch (IOException e) {\n          throw new IllegalStateException(e);\n        }\n      });\n      graphQlAnswer = bodyString.map(toObject).orElseThrow();","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-server-common/src/main/java/org/sonar/server/common/graphql/GraphQlClient.java#L116-L152","documentation":"GraphQlClient.executeCallAndDeserializeAnswer checks the HTTP status of the OkHttp response before parsing. Any non-2xx status (401, 403, 404, 5xx...) aborts with an IllegalStateException carrying the return code and raw response body, since a GraphQL answer cannot be expected from a failed HTTP call.","triggerScenarios":"Calling any GraphQlClient query (e.g. fetchValidDataOrThrow) against an endpoint returning 4xx/5xx: wrong base URL, expired/missing token, server outage, proxy errors, rate limiting.","commonSituations":"Expired API credentials returning 401; firewall/proxy intercepting with 403 or 502; the target service being down (503); pointing the client at a UI URL instead of the GraphQL endpoint (404).","solutions":["Inspect the return code and error message embedded in the exception to identify the server-side cause.","Verify the GraphQL endpoint URL and that the client targets the API path, not a UI page.","Check/renew authentication credentials (token) if the code is 401/403.","Check server health/status; retry with backoff for transient 5xx.","Confirm network/proxy configuration allows reaching the host."],"exampleFix":"// before\nRequest request = new Request.Builder().url(\"https://host/sonar\").build();\n// after\nRequest request = new Request.Builder()\n  .url(\"https://host/sonar/api/graphql\")\n  .header(\"Authorization\", \"Bearer \" + token)\n  .build();","handlingStrategy":"try-catch","validationCode":"// Preflight: check endpoint reachability\nHttpRequest req = HttpRequest.newBuilder(URI.create(baseUrl + \"/api/system/status\")).GET().build();\n// ensure 200 before issuing GraphQL queries","typeGuard":null,"tryCatchPattern":"try {\n  T data = graphQlClient.fetchValidDataOrThrow(...);\n} catch (IllegalStateException e) {\n  if (e.getMessage().contains(\"Return code 40\") ) renewToken();\n  else if (e.getMessage().contains(\"Return code 5\")) retryWithBackoff();\n  else throw e;\n}","preventionTips":["Point the client at the correct GraphQL API path with valid credentials.","Handle 401 by refreshing tokens before calls.","Add retries with backoff for transient 5xx.","Monitor endpoint availability in health checks."],"tags":["graphql","http","network"],"backgroundTag":"http-error-response","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}