gohugoio/hugo · error

unable to find alternative port to use

Error message

unable to find alternative port to use: %s

What it means

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.

Solutions

1. Reduce the number of running listeners; stop stale `hugo server`/dev processes.
2. Raise file/socket limits (`ulimit -n`) if you are running many servers.
3. Explicitly pass a known-free `--port` to bypass the auto-selection path.
4. Check container/seccomp policy if binds are being denied.

Example fix

// before
// many sockets in use; fallback TCPListen fails
// after
// $ hugo server --port=1314   (known-free explicit port)

import "github.com/gohugoio/hugo/helpers"
func validateFreePortExists() error {
  ln, err := helpers.TCPListen()
  if err != nil { return err }
  ln.Close()
  return nil
}

null

// When fallback port allocation fails, surface it and retry with an
// explicit, known-free port instead of looping.
if err := cmd.Execute(); err != nil {
  if strings.Contains(err.Error(), "unable to find alternative port") {
    // pick and pass an explicit --port known to be free
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• server startup failed
• failed to split baseURL hostport
• --appendPort=false not supported when in multihost mode
• cannot use --renderToMemory with --destination
• failed to clone

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/765b7ea5bee29694. Report an issue: GitHub.

Appendix: source

Thrown at commands/server.go:780

				return
			}
			c.serverPorts = make([]serverPortListener, len(conf.configs.Languages))
		}
		currentServerPort := c.serverPort
		for i := range c.serverPorts {
			l, err := net.Listen("tcp", net.JoinHostPort(c.serverInterface, strconv.Itoa(currentServerPort)))
			if err == nil {
				c.serverPorts[i] = serverPortListener{ln: l, p: currentServerPort}
			} else {
				if i == 0 && flags.Changed("port") {
					// port set explicitly by user -- he/she probably meant it!
					cerr = fmt.Errorf("server startup failed: %s", err)
					return
				}
				c.r.Println("port", currentServerPort, "already in use, attempting to use an available port")
				l, sp, err := helpers.TCPListen()
				if err != nil {
					cerr = fmt.Errorf("unable to find alternative port to use: %s", err)
					return
				}
				c.serverPorts[i] = serverPortListener{ln: l, p: sp.Port}
			}

			currentServerPort = c.serverPorts[i].p + 1
		}
	})

	return cerr
}

// fixURL massages the baseURL into a form needed for serving
// all pages correctly.
func (c *serverCommand) fixURL(baseURLFromConfig, baseURLFromFlag string, port int) (string, error) {
	certsSet := (c.tlsCertFile != "" && c.tlsKeyFile != "") || c.tlsAuto
	useLocalhost := false
	baseURL := baseURLFromFlag

View on GitHub (pinned to 52c9bd7908)