{"record":{"id":"e4cd045c560e332a","repo":"stanfordnlp/CoreNLP","slug":"could-not-start-a-local-server","errorCode":null,"errorMessage":"Could not start a local server!","messagePattern":"Could not start a local server!","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"src/edu/stanford/nlp/pipeline/WebServiceAnnotator.java","lineNumber":255,"sourceCode":"   * This is certainly called from {@link #annotate(Annotation)}, but can also\n   * be called from the constructor of the annotator to cache startup times.\n   *\n   * @throws TimeoutException Thrown if we could not connect to the server for the timeout period.\n   * @throws IOException Thrown if we could not start the server process.\n   */\n  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","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/stanfordnlp/CoreNLP/blob/1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a/src/edu/stanford/nlp/pipeline/WebServiceAnnotator.java#L237-L273","documentation":"WebServiceAnnotator.ensureServer attempts to launch the external annotator's local server process via startCommand/startServer. If startServer reports the process failed to start (non-null command but startServer returned false), it throws this IOException before any annotation request is made.","triggerScenarios":"The web service annotator is configured with a start command (e.g. a script or 'docker run ...') that exits immediately or fails to bind its port — such as a missing binary, wrong path, or a port already in use.","commonSituations":"Deploying to a machine without the external service installed, bad executable path in the start command, insufficient permissions to execute the script, or container runtime missing.","solutions":["Run the configured start command manually and fix whatever makes it fail (missing binary, bad flags, missing runtime)","Verify the port in the start command matches the annotator's configured target port and is free","Check process logs/stderr — ensure the server actually binds and stays alive before the client gives up","If the server is already running elsewhere, remove the start command so ensureServer skips local launch"],"exampleFix":"// before\nprops.setProperty(\"webservice.command\", \"/opt/annotators/missing-server.sh --port 8140\");\n// after\nprops.setProperty(\"webservice.command\", \"/opt/annotators/server.sh --port 8140\"); // ensure file exists and is executable","handlingStrategy":"validation","validationCode":"// Pre-flight: verify the start command exists and the port is free\nString cmd = props.getProperty(\"webservice.command\");\nif (cmd != null) {\n  String bin = cmd.split(\"\\\\s+\")[0];\n  if (!new java.io.File(bin).canExecute())\n    throw new IllegalStateException(\"Start command not executable: \" + bin);\n  int port = Integer.parseInt(props.getProperty(\"webservice.port\", \"8140\"));\n  try (var s = new java.net.ServerSocket(port)) { /* free */ }\n  catch (java.io.IOException e) { throw new IllegalStateException(\"Port \" + port + \" already in use\"); }\n}","typeGuard":null,"tryCatchPattern":"try {\n  pipeline.annotate(doc);\n} catch (java.io.IOException e) {\n  if (e.getMessage().contains(\"Could not start a local server\")) {\n    log.error(\"Start command failed: run it manually and fix startup errors\");\n  }\n  throw e;\n}","preventionTips":["Run the start command manually once before wiring it into the pipeline","Check that the executable path exists and has execute permission","Ensure the configured port is free and matches the server's bind port","Capture and log the server process's stdout/stderr for diagnosis"],"tags":["web-service","server-startup","process"],"backgroundTag":"server-failed-to-start","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"}