{"record":{"id":"765b7ea5bee29694","repo":"gohugoio/hugo","slug":"unable-to-find-alternative-port-to-use-s","errorCode":null,"errorMessage":"unable to find alternative port to use: %s","messagePattern":"unable to find alternative port to use: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"commands/server.go","lineNumber":780,"sourceCode":"\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\n// fixURL massages the baseURL into a form needed for serving\n// all pages correctly.\nfunc (c *serverCommand) fixURL(baseURLFromConfig, baseURLFromFlag string, port int) (string, error) {\n\tcertsSet := (c.tlsCertFile != \"\" && c.tlsKeyFile != \"\") || c.tlsAuto\n\tuseLocalhost := false\n\tbaseURL := baseURLFromFlag","sourceCodeStart":762,"sourceCodeEnd":798,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/commands/server.go#L762-L798","documentation":"When the requested port is busy and the user did not pin it, Hugo calls `helpers.TCPListen()` to grab any free ephemeral port. This wraps a failure of that fallback, meaning the OS could not allocate any free TCP listener at all.","triggerScenarios":"Fires when `helpers.TCPListen()` returns an error — the ephemeral port range is exhausted, all listeners are denied by policy, or the system's socket limit is hit.","commonSituations":"Severe port exhaustion (too many TIME_WAIT sockets / running dev servers); container/seccomp/SELinux policy denying `bind`; an extremely low `ulimit -n` or a locked-down network namespace.","solutions":["Reduce the number of running listeners; stop stale `hugo server`/dev processes.","Raise file/socket limits (`ulimit -n`) if you are running many servers.","Explicitly pass a known-free `--port` to bypass the auto-selection path.","Check container/seccomp policy if binds are being denied."],"exampleFix":"// before\n// many sockets in use; fallback TCPListen fails\n// after\n// $ hugo server --port=1314   (known-free explicit port)","handlingStrategy":"validation","validationCode":"import \"github.com/gohugoio/hugo/helpers\"\nfunc validateFreePortExists() error {\n  ln, err := helpers.TCPListen()\n  if err != nil { return err }\n  ln.Close()\n  return nil\n}","typeGuard":"null","tryCatchPattern":"// When fallback port allocation fails, surface it and retry with an\n// explicit, known-free port instead of looping.\nif err := cmd.Execute(); err != nil {\n  if strings.Contains(err.Error(), \"unable to find alternative port\") {\n    // pick and pass an explicit --port known to be free\n  }\n}","preventionTips":["Limit the number of concurrent dev servers running on the host.","Raise `ulimit -n` when running many listeners.","Pass an explicit free `--port` rather than relying on auto-selection."],"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"}