{"record":{"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/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/commands/server.go#L756-L792","documentation":"`createServerPorts` calls `net.Listen(\"tcp\", host:port)` for the configured port. If that fails AND the user set `--port` explicitly, Hugo refuses to fall back and wraps the listen error as `server startup failed`. The explicit-port contract is: the user meant this port, so do not silently relocate.","triggerScenarios":"Fires on the first port (`i == 0`) when `--port` was changed on the CLI and `net.Listen` returns an error — typically `bind: address already in use` or `bind: permission denied` (privileged port).","commonSituations":"Another process (often a previous `hugo server` or a dev server) holds the chosen port; requesting a privileged port `<1024` as a non-root user; a port blocked by firewall/SELinux.","solutions":["Free the port: find and stop the occupying process (`lsof -i :PORT`).","Choose a different `--port` that is known free.","Use a non-privileged port (>1024) unless running as root with explicit need.","Drop the explicit `--port` to let Hugo auto-select an alternative."],"exampleFix":"// before\n// $ hugo server --port=1313   (already in use)\n// after\n// $ lsof -ti:1313 | xargs kill ; hugo server --port=1313","handlingStrategy":"validation","validationCode":"import (\n  \"net\"\n  \"strconv\"\n)\nfunc validatePortFree(host string, port int) error {\n  ln, err := net.Listen(\"tcp\", net.JoinHostPort(host, strconv.Itoa(port)))\n  if err != nil { return err }\n  ln.Close()\n  return nil\n}","typeGuard":"null","tryCatchPattern":"// If the pinned port is busy, free it or let Hugo auto-select by\n// dropping the explicit --port.\nif err := cmd.Execute(); err != nil {\n  if strings.Contains(err.Error(), \"server startup failed\") { /* free port or drop --port */ }\n}","preventionTips":["Stop previous `hugo server`/dev processes before reusing a port.","Avoid privileged ports (<1024) as a non-root user.","Drop the explicit `--port` to let Hugo auto-select a free one."],"tags":["hugo","server","network","port","bind"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}