{"record":{"id":"5dfe9c4e0d6d596e","repo":"stanfordnlp/CoreNLP","slug":"could-not-connect-to-annotator","errorCode":null,"errorMessage":"Could not connect to annotator: ","messagePattern":"Could not connect to annotator: ","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"critical","filePath":"src/edu/stanford/nlp/pipeline/WebServiceAnnotator.java","lineNumber":261,"sourceCode":"  protected void ensureServer() throws TimeoutException, IOException {\n    long startTime = System.currentTimeMillis();\n\n    // if the server was active last time we checked, see if the server is still active\n    if (serverWasActive) {\n      if (ready(false))\n        return;\n    }\n\n    // 1. Start a server, if applicable\n    boolean serverStarted = startCommand().map(this::startServer).orElse(true);\n    if (!serverStarted) {\n      throw new IOException(\"Could not start a local server!\");\n    }\n\n    // 2. Wait for the target server to come online\n    while (!everLive) {\n      if (System.currentTimeMillis() > startTime + CONNECT_TIMEOUT) {\n        throw new TimeoutException(\"Could not connect to annotator: \" + this);\n      }\n      if (!live()) {\n        try {\n          Thread.sleep(1000);\n        } catch (InterruptedException ignored) {}\n      } else {\n        everLive = true;\n      }\n    }\n    log.info(\"Got liveness from server for \" + this);\n\n    // 3. Wait for the target server to become ready\n    synchronized (this) {\n      if (this.server.isPresent()) {\n        while (!this.server.get().ready) {\n          if (System.currentTimeMillis() > startTime + CONNECT_TIMEOUT) {\n            throw new TimeoutException(\"Never got readiness from annotator: \" + this);\n          }","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/stanfordnlp/CoreNLP/blob/1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a/src/edu/stanford/nlp/pipeline/WebServiceAnnotator.java#L243-L279","documentation":"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.","triggerScenarios":"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.","commonSituations":"Model startup exceeding the default connect timeout, wrong port/host configuration, docker port mapping mistakes, or network policies blocking localhost/remote connections.","solutions":["Increase the connect timeout property (e.g. webservice.connectTimeout) to allow slow model startup","Verify the annotator's URL/port matches where the server actually listens (check docker -p mappings, --port flags)","Test reachability manually: curl http://host:port/ and confirm a response","Check server logs for crashes or binding errors during startup"],"exampleFix":"// before\nprops.setProperty(\"webservice.connectTimeout\", \"10000\");\n// after\nprops.setProperty(\"webservice.connectTimeout\", \"120000\"); // allow slow model load","handlingStrategy":"retry","validationCode":"// Pre-flight reachability check with a generous deadline\nlong deadline = System.currentTimeMillis() + 120_000;\nboolean live = false;\nwhile (System.currentTimeMillis() < deadline && !live) {\n  try (var c = (java.net.HttpURLConnection) new java.net.URL(url).openConnection()) {\n    c.setConnectTimeout(2000); c.setRequestMethod(\"GET\");\n    live = c.getResponseCode() < 500;\n  } catch (java.io.IOException ignored) {}\n  if (!live) try { Thread.sleep(1000); } catch (InterruptedException ignored) {}\n}\nif (!live) throw new IllegalStateException(\"Server never became live at \" + url);","typeGuard":null,"tryCatchPattern":"try {\n  pipeline.annotate(doc);\n} catch (java.util.concurrent.TimeoutException e) {\n  if (e.getMessage().contains(\"Could not connect to annotator\")) {\n    // increase timeout and rebuild, or verify host/port and server startup\n    props.setProperty(\"webservice.connectTimeout\", \"300000\");\n  }\n}","preventionTips":["Increase connectTimeout when models load slowly","Verify host/port with curl before constructing the pipeline","Check docker port mappings when the service runs in a container","Monitor server startup logs to know typical warm-up duration"],"tags":["web-service","timeout","network"],"backgroundTag":"request-timeout","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"}