stanfordnlp/CoreNLP · error · RuntimeException

Could not annotate document after 3 tries:

Error message

Could not annotate document after 3 tries:

What it means

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).

Solutions

  1. Inspect the wrapped cause 'e' — it names the actual per-request failure (HTTP status, IOException, etc.)
  2. Check server logs for the exception thrown while processing the document
  3. Reduce document size or batch size if payload limits or timeouts are the cause
  4. Verify client/server version compatibility and retry with a healthy, warmed-up server

Example fix

// before
pipeline.annotate(largeAnnotation); // 3 failures on 50MB doc
// after
List<CoreDocument> chunks = splitDocument(largeAnnotation, 1000); // annotate in chunks
chunks.forEach(pipeline::annotate);
Defensive patterns

Strategy: try-catch

Validate before calling

// Check payload size and service health before annotating
long maxBytes = 5_000_000;
if (serializedDoc.length > maxBytes)
  throw new IllegalStateException("Document too large for web service; split it");
int code = ((java.net.HttpURLConnection) new java.net.URL(url).openConnection()).getResponseCode();
if (code != 200) throw new IllegalStateException("Service unhealthy: HTTP " + code);

Try / catch

try {
  pipeline.annotate(doc);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Could not annotate document after 3 tries")) {
    Throwable cause = e.getCause();
    log.error("Annotation failed 3x; root cause: " + cause, cause);
    // fall back to a local annotator or requeue the document
  } else throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

AI-assisted analysis of stanfordnlp/CoreNLP@1b7edd19c4 (2026-09-10). Data as JSON: /api/errors/ddb813b65b8843bc. Report an issue: GitHub.

Appendix: source

Thrown at src/edu/stanford/nlp/pipeline/WebServiceAnnotator.java:380

        } else {
          throw new RuntimeException(e);
        }

      } catch (ShouldRetryException e) {

        // 3B. We've failed to annotate, but should maybe retry
        // 3B.1. Stop the server, if this is our third try
        synchronized (this) {
          if (tries >= 2 && this.server.isPresent()) {
            this.server.get().kill();
            this.server = Optional.empty();
          }
        }
        // 3B.2. Retry
        if (tries < 3) {
          annotate(annotation, tries + 1);
        } else {
          throw new RuntimeException("Could not annotate document after 3 tries:", e);
        }

      }
    } catch (TimeoutException | IOException e) {
      throw new RuntimeException("Could not ensure a server:", e);
    }
  }


  /**
   * A quick script to debug server lifecycle.
   */
  public static void main(String[] args) throws InterruptedException {
    WebServiceAnnotator annotator = new WebServiceAnnotator(){

      @Override
      public Set<Class<? extends CoreAnnotation>> requirementsSatisfied() {
        return Collections.emptySet();

View on GitHub (pinned to 1b7edd19c4)