{"record":{"id":"d134f151f0763643","repo":"languagetool-org/languagetool","slug":"http-server-start-failed","errorCode":null,"errorMessage":"http_server_start_failed","messagePattern":"http_server_start_failed","errorType":"exception","errorClass":"PortBindingException","httpStatus":null,"severity":"critical","filePath":"languagetool-server/src/main/java/org/languagetool/server/HTTPServer.java","lineNumber":128,"sourceCode":"      httpHandler = new LanguageToolHttpHandler(config, allowedIps, runInternally, limiter, errorLimiter, workQueue, this);\n      //check if port is 0 for get random port from range\n      if (port == 0) {\n        int minPort = config.getMinPort();\n        int maxPort = config.getMaxPort();\n        port = getPortFromRange(minPort, maxPort);\n      }\n      InetSocketAddress address = host != null ? new InetSocketAddress(host, port) : new InetSocketAddress(port);\n      server = HttpServer.create(address, 0);\n      server.createContext(\"/\", httpHandler);\n      server.setExecutor(executorService);\n\n      if (config.isPrometheusMonitoring()) {\n        ServerMetricsCollector.init(config);\n      }\n    } catch (Exception e) {\n      ResourceBundle messages = JLanguageTool.getMessageBundle();\n      String message = Tools.i18n(messages, \"http_server_start_failed\", host, Integer.toString(port));\n      throw new PortBindingException(message, e);\n    }\n  }\n  \n  private int getPortFromRange(int minPort, int maxPort) throws IOException {\n    if (minPort > 0 && minPort < maxPort) {\n         log.info(\"Try to find a free Port for Server in range {}-{}\", minPort, maxPort);\n         for (int p = minPort; p <= maxPort; p++) {\n           try {\n             log.info(\"Check port {}\", p);\n             ServerSocket serverSocket = new ServerSocket(p);\n             port = serverSocket.getLocalPort();\n             serverSocket.close();\n             log.info(\"Port {} is available.\", p);\n             return p;\n           } catch (IOException ex) {\n             log.debug(\"Port {} is not available.\", p);\n           }\n         }","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/languagetool-org/languagetool/blob/2e990059ce67d5e2a0f7f7ca5d31160c6709df4b/languagetool-server/src/main/java/org/languagetool/server/HTTPServer.java#L110-L146","documentation":"HTTPServer's constructor wraps listener setup failures: when the server cannot bind to host:port (or another exception occurs during startup), it throws PortBindingException with the localized 'http_server_start_failed' message. Same port-binding failure family as the HTTPS server, but for plain HTTP.","triggerScenarios":"Starting the HTTP server on a port already in use (BindException); binding to a host address not present on the machine; port-range exhaustion if getPortFromRange cannot find a free port.","commonSituations":"Another LT instance or other service already on the port; Docker port conflicts; stale process from a crashed run; min/max port range fully occupied in auto-port mode.","solutions":["Identify and stop the process holding the port: lsof -i :<port> / ss -ltnp.","Change the configured port or widen the port range in the config.","Kill stale LT server processes (ps aux | grep languagetool).","Verify the host/interface value in config matches an address available on the machine."],"exampleFix":"// before\nport = 8080   // occupied by nginx\n// after\nport = 8081   # or stop nginx on 8080 first","handlingStrategy":"try-catch","validationCode":"// check port availability before startup\ntry (ServerSocket s = new ServerSocket()) {\n  s.bind(new InetSocketAddress(host, port));\n} catch (IOException e) {\n  throw new IllegalStateException(\"HTTP port \" + port + \" already in use\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  httpServer = new HTTPServer(config, false, allowedIps);\n} catch (PortBindingException e) {\n  log.error(\"HTTP port {} in use\", config.getPort(), e);\n  System.exit(1);\n}","preventionTips":["Reserve distinct ports for each service instance","Use the port-range config so the server auto-picks a free port","Check for stale processes after crashes before restart","Validate container/host port mappings don't overlap"],"tags":["port-binding","network","http","server-startup"],"backgroundTag":"address-already-in-use","analyzedSha":"2e990059ce67d5e2a0f7f7ca5d31160c6709df4b","analyzedAt":"2026-09-06T09:20:17.015Z","contentChangedAt":"2026-09-06T09:20:17.015Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}