{"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":"critical","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/8a468df065a75c1c7cf9f6850f32148746590ea5/commands/server.go#L762-L798","documentation":"When the desired port is busy and the user did not explicitly pin it, Hugo prints a notice and asks the OS for any free port via `helpers.TCPListen()` (listen on port 0). This error means even that fallback failed — the OS refused to hand out an ephemeral port, which indicates a system-level networking problem rather than a Hugo misconfiguration.","triggerScenarios":"During `hugo server` startup after the default/derived port was in use: the fallback `net.Listen(\"tcp\", \":0\")` fails — ephemeral port range exhausted, per-process fd limit reached, no networking stack available, or sandbox/container policies blocking listeners.","commonSituations":"Heavily loaded CI machines or dev boxes with thousands of sockets in TIME_WAIT; restrictive sandboxes/seccomp profiles or minimal containers without network permission; extremely low `ulimit -n`; broken loopback interface.","solutions":["Check system health: `ulimit -n`, count of open sockets (`ss -s`), and whether loopback is up.","Free sockets/processes hogging the ephemeral range, or wait for TIME_WAIT sockets to drain.","In containers/sandboxes, grant network-listen capability or run the server outside the sandbox.","Retry with an explicit free port (`-p <n>`) to bypass the ephemeral allocation path."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"ln, err := net.Listen(\"tcp\", \":0\") // confirm the OS can still hand out ephemeral ports\nif err != nil { return err }\nln.Close()","typeGuard":null,"tryCatchPattern":"if err := startServer(); err != nil && strings.Contains(err.Error(), \"alternative port\") {\n    // fall back to an explicit known-free port\n    err = startServerWithFlag(\"--port\", \"1414\")\n}","preventionTips":["Pass an explicit --port you know is free instead of relying on auto-selection","Clean up orphaned dev-server processes (they exhaust the probe range)","In containers/CI, ensure the network namespace permits listening sockets"],"tags":["hugo-server","network","system-resources"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}