{"record":{"id":"ddb813b65b8843bc","repo":"stanfordnlp/CoreNLP","slug":"could-not-annotate-document-after-3-tries","errorCode":null,"errorMessage":"Could not annotate document after 3 tries:","messagePattern":"Could not annotate document after 3 tries:","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/edu/stanford/nlp/pipeline/WebServiceAnnotator.java","lineNumber":380,"sourceCode":"        } else {\n          throw new RuntimeException(e);\n        }\n\n      } catch (ShouldRetryException e) {\n\n        // 3B. We've failed to annotate, but should maybe retry\n        // 3B.1. Stop the server, if this is our third try\n        synchronized (this) {\n          if (tries >= 2 && this.server.isPresent()) {\n            this.server.get().kill();\n            this.server = Optional.empty();\n          }\n        }\n        // 3B.2. Retry\n        if (tries < 3) {\n          annotate(annotation, tries + 1);\n        } else {\n          throw new RuntimeException(\"Could not annotate document after 3 tries:\", e);\n        }\n\n      }\n    } catch (TimeoutException | IOException e) {\n      throw new RuntimeException(\"Could not ensure a server:\", e);\n    }\n  }\n\n\n  /**\n   * A quick script to debug server lifecycle.\n   */\n  public static void main(String[] args) throws InterruptedException {\n    WebServiceAnnotator annotator = new WebServiceAnnotator(){\n\n      @Override\n      public Set<Class<? extends CoreAnnotation>> requirementsSatisfied() {\n        return Collections.emptySet();","sourceCodeStart":362,"sourceCodeEnd":398,"githubUrl":"https://github.com/stanfordnlp/CoreNLP/blob/1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a/src/edu/stanford/nlp/pipeline/WebServiceAnnotator.java#L362-L398","documentation":"WebServiceAnnotator.annotate retries a failed annotation request up to 3 times. If the request still fails on the third attempt, it wraps the last exception in this RuntimeException, meaning the server is reachable but repeatedly fails to annotate the document (HTTP errors, serialization problems, server-side exceptions).","triggerScenarios":"Three consecutive failed annotate requests: server returns non-2xx responses, request payloads exceed limits, the document causes a server-side exception, or intermittent connection drops that persist across retries.","commonSituations":"Flaky network between client and service, server overload/5xx responses, documents too large for the service's limits, or a version mismatch where the server cannot parse the client's serialized request.","solutions":["Inspect the wrapped cause 'e' — it names the actual per-request failure (HTTP status, IOException, etc.)","Check server logs for the exception thrown while processing the document","Reduce document size or batch size if payload limits or timeouts are the cause","Verify client/server version compatibility and retry with a healthy, warmed-up server"],"exampleFix":"// before\npipeline.annotate(largeAnnotation); // 3 failures on 50MB doc\n// after\nList<CoreDocument> chunks = splitDocument(largeAnnotation, 1000); // annotate in chunks\nchunks.forEach(pipeline::annotate);","handlingStrategy":"try-catch","validationCode":"// Check payload size and service health before annotating\nlong maxBytes = 5_000_000;\nif (serializedDoc.length > maxBytes)\n  throw new IllegalStateException(\"Document too large for web service; split it\");\nint code = ((java.net.HttpURLConnection) new java.net.URL(url).openConnection()).getResponseCode();\nif (code != 200) throw new IllegalStateException(\"Service unhealthy: HTTP \" + code);","typeGuard":null,"tryCatchPattern":"try {\n  pipeline.annotate(doc);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Could not annotate document after 3 tries\")) {\n    Throwable cause = e.getCause();\n    log.error(\"Annotation failed 3x; root cause: \" + cause, cause);\n    // fall back to a local annotator or requeue the document\n  } else throw e;\n}","preventionTips":["Always inspect getCause() to find the true per-request failure","Split very large documents into chunks below service limits","Monitor server-side 5xx rates and scale the service accordingly","Pin matching client/server versions to avoid serialization mismatches"],"tags":["web-service","http","retry-exhausted"],"backgroundTag":"api-request-failed","analyzedSha":"1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a","analyzedAt":"2026-09-10T02:24:07.274Z","contentChangedAt":"2026-09-10T02:24:07.274Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}