stanfordnlp/CoreNLP · critical · TimeoutException

Could not connect to annotator:

Error message

Could not connect to annotator: 

What it means

WebServiceAnnotator.ensureServer polls the annotator's endpoint until it responds. If the server never becomes live within CONNECT_TIMEOUT milliseconds, it throws this TimeoutException identifying the annotator.

Solutions

1. Increase the connect timeout property (e.g. webservice.connectTimeout) to allow slow model startup
2. Verify the annotator's URL/port matches where the server actually listens (check docker -p mappings, --port flags)
3. Test reachability manually: curl http://host:port/ and confirm a response
4. Check server logs for crashes or binding errors during startup

Example fix

// before
props.setProperty("webservice.connectTimeout", "10000");
// after
props.setProperty("webservice.connectTimeout", "120000"); // allow slow model load

// Pre-flight reachability check with a generous deadline
long deadline = System.currentTimeMillis() + 120_000;
boolean live = false;
while (System.currentTimeMillis() < deadline && !live) {
  try (var c = (java.net.HttpURLConnection) new java.net.URL(url).openConnection()) {
    c.setConnectTimeout(2000); c.setRequestMethod("GET");
    live = c.getResponseCode() < 500;
  } catch (java.io.IOException ignored) {}
  if (!live) try { Thread.sleep(1000); } catch (InterruptedException ignored) {}
}
if (!live) throw new IllegalStateException("Server never became live at " + url);

try {
  pipeline.annotate(doc);
} catch (java.util.concurrent.TimeoutException e) {
  if (e.getMessage().contains("Could not connect to annotator")) {
    // increase timeout and rebuild, or verify host/port and server startup
    props.setProperty("webservice.connectTimeout", "300000");
  }
}

When it happens

Trigger: The target server is slow to boot (large model loading), is listening on a different host/port than the annotator's URL, is blocked by a firewall, or crashed after start — so live() keeps returning false past the timeout.

Common situations: Model startup exceeding the default connect timeout, wrong port/host configuration, docker port mapping mistakes, or network policies blocking localhost/remote connections.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• Never got readiness from annotator:
• Could not ensure a server:
• Expected a tree
• Invalid subnet
• Could not start a local server!

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

Appendix: source

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

  protected void ensureServer() throws TimeoutException, IOException {
    long startTime = System.currentTimeMillis();

    // if the server was active last time we checked, see if the server is still active
    if (serverWasActive) {
      if (ready(false))
        return;
    }

    // 1. Start a server, if applicable
    boolean serverStarted = startCommand().map(this::startServer).orElse(true);
    if (!serverStarted) {
      throw new IOException("Could not start a local server!");
    }

    // 2. Wait for the target server to come online
    while (!everLive) {
      if (System.currentTimeMillis() > startTime + CONNECT_TIMEOUT) {
        throw new TimeoutException("Could not connect to annotator: " + this);
      }
      if (!live()) {
        try {
          Thread.sleep(1000);
        } catch (InterruptedException ignored) {}
      } else {
        everLive = true;
      }
    }
    log.info("Got liveness from server for " + this);

    // 3. Wait for the target server to become ready
    synchronized (this) {
      if (this.server.isPresent()) {
        while (!this.server.get().ready) {
          if (System.currentTimeMillis() > startTime + CONNECT_TIMEOUT) {
            throw new TimeoutException("Never got readiness from annotator: " + this);
          }

View on GitHub (pinned to 1b7edd19c4)