{"id":"19d4c96d7a846ec1","repo":"gohugoio/hugo","slug":"server-startup-failed-s","errorCode":null,"errorMessage":"server startup failed: %s","messagePattern":"server startup failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"commands/server.go","lineNumber":774,"sourceCode":"\tc.withConf(func(conf *commonConfig) {\n\t\tisMultihost := conf.configs.IsMultihost\n\t\tc.serverPorts = make([]serverPortListener, 1)\n\t\tif isMultihost {\n\t\t\tif !c.serverAppend {\n\t\t\t\tcerr = errors.New(\"--appendPort=false not supported when in multihost mode\")\n\t\t\t\treturn\n\t\t\t}\n\t\t\tc.serverPorts = make([]serverPortListener, len(conf.configs.Languages))\n\t\t}\n\t\tcurrentServerPort := c.serverPort\n\t\tfor i := range c.serverPorts {\n\t\t\tl, err := net.Listen(\"tcp\", net.JoinHostPort(c.serverInterface, strconv.Itoa(currentServerPort)))\n\t\t\tif err == nil {\n\t\t\t\tc.serverPorts[i] = serverPortListener{ln: l, p: currentServerPort}\n\t\t\t} else {\n\t\t\t\tif i == 0 && flags.Changed(\"port\") {\n\t\t\t\t\t// port set explicitly by user -- he/she probably meant it!\n\t\t\t\t\tcerr = fmt.Errorf(\"server startup failed: %s\", err)\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t\tc.r.Println(\"port\", currentServerPort, \"already in use, attempting to use an available port\")\n\t\t\t\tl, sp, err := helpers.TCPListen()\n\t\t\t\tif err != nil {\n\t\t\t\t\tcerr = fmt.Errorf(\"unable to find alternative port to use: %s\", err)\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t\tc.serverPorts[i] = serverPortListener{ln: l, p: sp.Port}\n\t\t\t}\n\n\t\t\tcurrentServerPort = c.serverPorts[i].p + 1\n\t\t}\n\t})\n\n\treturn cerr\n}\n","sourceCodeStart":756,"sourceCodeEnd":792,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/commands/server.go#L756-L792","documentation":"Hugo tried to bind its TCP listener on the interface/port you explicitly requested and `net.Listen` failed. Because the `--port` flag was set by the user (flag marked Changed for the first listener), Hugo treats the intent as deliberate and fails instead of silently picking another port; the underlying OS error (e.g. `address already in use`, `permission denied`) is included.","triggerScenarios":"`hugo server --port <n>` (or `-p`) where binding `<bind-interface>:<n>` fails: the port is occupied by another process, `<n>` is a privileged port (<1024) without rights, or `--bind` names an address not present on the machine.","commonSituations":"A previous `hugo server` (or another dev server) still holding port 1313; two Hugo projects started with the same `-p`; `--bind 0.0.0.0` vs an unavailable interface IP in containers/WSL; choosing port 80/443 without elevation.","solutions":["Free the port: find the holder with `lsof -i :<port>` / `ss -ltnp` and stop it, or pick another port with `-p`.","Omit `--port` entirely — without an explicit port, Hugo automatically falls back to a free port.","For privileged ports, use a port ≥1024 or run behind a proxy instead of elevating Hugo.","Verify the `--bind` address exists on this host (common in Docker/WSL setups)."],"exampleFix":"# before\nhugo server -p 1313   # error: listen tcp 127.0.0.1:1313: bind: address already in use\n# after\nhugo server -p 1314   # or: hugo server (auto-picks a free port)","handlingStrategy":"retry","validationCode":"// check the port is free before starting\nln, err := net.Listen(\"tcp\", net.JoinHostPort(iface, port))\nif err != nil { return fmt.Errorf(\"port %s unavailable: %w\", port, err) }\nln.Close()","typeGuard":null,"tryCatchPattern":"if err := startServer(); err != nil {\n    // retry once on a different port or after freeing the conflicting process\n    log.Printf(\"startup failed: %v — retrying on alternate port\", err)\n    err = startServerOnPort(altPort)\n}","preventionTips":["Kill stale hugo/dev-server processes holding the port before restart","Bind to 127.0.0.1 unless LAN exposure is intended; privileged ports (<1024) need elevated rights","Log and inspect the wrapped error — it usually names the bind failure"],"tags":["hugo-server","network","port-binding"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}