{"record":{"id":"9cafcb10d8424571","repo":"languagetool-org/languagetool","slug":"could-not-connect-to-server-at-serverbaseurl","errorCode":null,"errorMessage":"Could not connect to server at ${serverBaseUrl}","messagePattern":"Could not connect to server at (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"languagetool-http-client/src/main/java/org/languagetool/remote/RemoteLanguageTool.java","lineNumber":230,"sourceCode":"    HttpURLConnection conn = getConnection(postData, checkUrl);\n    try {\n      if (conn.getResponseCode() == HttpURLConnection.HTTP_OK) {\n        try (InputStream inputStream = conn.getInputStream()) {\n          StringBuilder sb = new StringBuilder();\n          try (InputStreamReader isr = new InputStreamReader(inputStream, \"utf-8\");\n               BufferedReader br = new BufferedReader(isr)) {\n            String line = br.readLine();\n            return Integer.parseInt(line);\n          }\n        }\n      } else {\n        try (InputStream inputStream = conn.getErrorStream()) {\n          String error = readStream(inputStream, \"utf-8\");\n          throw new RuntimeException(\"Got error: \" + error + \" - HTTP response code \" + conn.getResponseCode());\n        }\n      }\n    } catch (ConnectException e) {\n      throw new RuntimeException(\"Could not connect to server at \" + serverBaseUrl, e);\n    } catch (Exception e) {\n      throw new RuntimeException(e);\n    } finally {\n      conn.disconnect();\n    }\n  }\n\n  HttpURLConnection getConnection(byte[] postData, URL url) {\n    try {\n      HttpURLConnection conn = (HttpURLConnection) url.openConnection();\n      conn.setDoOutput(true);\n      conn.setInstanceFollowRedirects(false);\n      conn.setRequestMethod(\"POST\");\n      conn.setRequestProperty(\"Content-Type\", \"application/x-www-form-urlencoded\");\n      conn.setRequestProperty(\"charset\", \"utf-8\");\n      conn.setRequestProperty(\"Content-Length\", Integer.toString(postData.length));\n      try (DataOutputStream wr = new DataOutputStream(conn.getOutputStream())) {\n        wr.write(postData);","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/languagetool-org/languagetool/blob/2e990059ce67d5e2a0f7f7ca5d31160c6709df4b/languagetool-http-client/src/main/java/org/languagetool/remote/RemoteLanguageTool.java#L212-L248","documentation":"RemoteLanguageTool wraps a java.net.ConnectException in a RuntimeException when a TCP connection to the configured LanguageTool server URL cannot be established. Nothing answered at serverBaseUrl — the request never reached the application layer.","triggerScenarios":"Calling any RemoteLanguageTool method (here getMaxTextLength) when the server process is not running, the host/port in serverBaseUrl is wrong, a firewall drops the connection, or the server crashed.","commonSituations":"Forgot to start languagetool-server.jar; connecting from a container to 'localhost' instead of a service hostname; wrong port; server bound to 127.0.0.1 while called remotely.","solutions":["Start the LanguageTool server (java -jar languagetool-server.jar) and confirm the port is listening (curl http://host:port/v2/languages)","Correct host/port in the URL passed to RemoteLanguageTool; in containers use the service DNS name, not localhost","Check firewall/network policy between client and server","Add retry/backoff around client calls if the server is known to restart"],"exampleFix":"// before\nRemoteLanguageTool lt = new RemoteLanguageTool(\"http://localhost:8081\"); // server not started\n// after\n// start server first:  java -jar languagetool-server.jar --port 8081 --public\nRemoteLanguageTool lt = new RemoteLanguageTool(\"http://localhost:8081\");","handlingStrategy":"retry","validationCode":"try (Socket s = new Socket()) {\n  s.connect(new InetSocketAddress(host, port), 3000); // throws ConnectException if refused\n}","typeGuard":"static boolean canConnect(String host, int port) {\n  try (Socket s = new Socket()) { s.connect(new InetSocketAddress(host, port), 3000); return true; }\n  catch (IOException e) { return false; }\n}","tryCatchPattern":"try {\n  lt.check(text);\n} catch (RuntimeException e) {\n  if (e.getCause() instanceof ConnectException) {\n    // server down or wrong host/port: retry with backoff, then alert\n  } else throw e;\n}","preventionTips":["Start the LT server before client calls; verify with curl","Use service DNS names, not localhost, inside containers","Add exponential backoff retries for transient downtime"],"tags":["java","network","connection"],"backgroundTag":"connection-refused","analyzedSha":"2e990059ce67d5e2a0f7f7ca5d31160c6709df4b","analyzedAt":"2026-09-06T09:20:17.015Z","contentChangedAt":"2026-09-06T09:20:17.015Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}