languagetool-org/languagetool · error · RuntimeException

Could not connect to server at ${serverBaseUrl}

Error message

Could not connect to server at ${serverBaseUrl}

What it means

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.

Source

Thrown at languagetool-http-client/src/main/java/org/languagetool/remote/RemoteLanguageTool.java:230

    HttpURLConnection conn = getConnection(postData, checkUrl);
    try {
      if (conn.getResponseCode() == HttpURLConnection.HTTP_OK) {
        try (InputStream inputStream = conn.getInputStream()) {
          StringBuilder sb = new StringBuilder();
          try (InputStreamReader isr = new InputStreamReader(inputStream, "utf-8");
               BufferedReader br = new BufferedReader(isr)) {
            String line = br.readLine();
            return Integer.parseInt(line);
          }
        }
      } else {
        try (InputStream inputStream = conn.getErrorStream()) {
          String error = readStream(inputStream, "utf-8");
          throw new RuntimeException("Got error: " + error + " - HTTP response code " + conn.getResponseCode());
        }
      }
    } catch (ConnectException e) {
      throw new RuntimeException("Could not connect to server at " + serverBaseUrl, e);
    } catch (Exception e) {
      throw new RuntimeException(e);
    } finally {
      conn.disconnect();
    }
  }

  HttpURLConnection getConnection(byte[] postData, URL url) {
    try {
      HttpURLConnection conn = (HttpURLConnection) url.openConnection();
      conn.setDoOutput(true);
      conn.setInstanceFollowRedirects(false);
      conn.setRequestMethod("POST");
      conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
      conn.setRequestProperty("charset", "utf-8");
      conn.setRequestProperty("Content-Length", Integer.toString(postData.length));
      try (DataOutputStream wr = new DataOutputStream(conn.getOutputStream())) {
        wr.write(postData);

View on GitHub (pinned to 2e990059ce)

Solutions

  1. Start the LanguageTool server (java -jar languagetool-server.jar) and confirm the port is listening (curl http://host:port/v2/languages)
  2. Correct host/port in the URL passed to RemoteLanguageTool; in containers use the service DNS name, not localhost
  3. Check firewall/network policy between client and server
  4. Add retry/backoff around client calls if the server is known to restart

Example fix

// before
RemoteLanguageTool lt = new RemoteLanguageTool("http://localhost:8081"); // server not started
// after
// start server first:  java -jar languagetool-server.jar --port 8081 --public
RemoteLanguageTool lt = new RemoteLanguageTool("http://localhost:8081");
Defensive patterns

Strategy: retry

Validate before calling

try (Socket s = new Socket()) {
  s.connect(new InetSocketAddress(host, port), 3000); // throws ConnectException if refused
}

Type guard

static boolean canConnect(String host, int port) {
  try (Socket s = new Socket()) { s.connect(new InetSocketAddress(host, port), 3000); return true; }
  catch (IOException e) { return false; }
}

Try / catch

try {
  lt.check(text);
} catch (RuntimeException e) {
  if (e.getCause() instanceof ConnectException) {
    // server down or wrong host/port: retry with backoff, then alert
  } else throw e;
}

Prevention

When it happens

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

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

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of languagetool-org/languagetool@2e990059ce (2026-09-06). Data as JSON: /api/errors/9cafcb10d8424571. Report an issue: GitHub.