evanw/esbuild · error

Invalid port number

Error message

Invalid port number: %s

What it means

When parsing the --serve port from CLI arguments, esbuild converts the port text to an int64 using strconv.ParseInt and validates it is within the valid TCP port range (0 to 65535, i.e. 0xFFFF). This error fires when the port is negative or exceeds 65535. Port 0 is special-cased to mean auto-select from 8000.

Solutions

1. Use a port number between 0 and 65535 (0 means try port 8000)
2. Validate the port from environment variables before passing to esbuild CLI
3. Check for common typos like extra digits or negative signs

Example fix

# before
esbuild --serve=99999
# after
esbuild --serve=8000

function validatePort(portStr) {
  const port = parseInt(portStr, 10)
  if (isNaN(port) || port < 0 || port > 65535) {
    throw new Error(`Port must be between 0 and 65535, got: ${portStr}`)
  }
  return port === 0 ? 8000 : port // esbuild uses 8000 as default for port 0
}
const port = validatePort(process.env.PORT || '8000')
// then: esbuild --serve=${port}

When it happens

Trigger: Running the esbuild CLI with --serve=99999, --serve=-1, or a port value from an environment variable that is out of the valid range.

Common situations: Port numbers sourced from environment variables or scripts with out-of-range values, or typos like an extra digit (e.g. 80000 instead of 8000).

Related errors

• Cannot serve without an output path
• Invalid origin
• Must specify both key and certificate for HTTPS
• Output directory must be contained in serve directory
• Cannot compute relative path from

AI-assisted analysis of evanw/esbuild@f6058f8364 (2026-08-09). Data as JSON: /api/errors/853c47282bd15bb1. Report an issue: GitHub.

Appendix: source

Thrown at pkg/cli/cli_impl.go:1475

	// Specifying the host is optional
	var err error
	if strings.ContainsRune(portText, ':') {
		host, portText, err = net.SplitHostPort(portText)
		if err != nil {
			return api.ServeOptions{}, nil, err
		}
	}

	// Parse the port
	var port int64
	if portText != "" {
		port, err = strconv.ParseInt(portText, 10, 32)
		if err != nil {
			return api.ServeOptions{}, nil, err
		}
		if port < 0 || port > 0xFFFF {
			return api.ServeOptions{}, nil, fmt.Errorf("Invalid port number: %s", portText)
		}
		if port == 0 {
			// 0 is the default value in Go, which we interpret as "try to
			// pick port 8000". So Go uses -1 as the sentinel value instead.
			port = -1
		}
	}

	return api.ServeOptions{
		Port:     int(port),
		Host:     host,
		Servedir: servedir,
		Keyfile:  keyfile,
		Certfile: certfile,
		Fallback: fallback,
		CORS: api.CORSOptions{
			Origin: corsOrigin,
		},

View on GitHub (pinned to f6058f8364)