{"record":{"id":"853c47282bd15bb1","repo":"evanw/esbuild","slug":"invalid-port-number-s","errorCode":null,"errorMessage":"Invalid port number: %s","messagePattern":"Invalid port number: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/cli/cli_impl.go","lineNumber":1475,"sourceCode":"\n\t// Specifying the host is optional\n\tvar err error\n\tif strings.ContainsRune(portText, ':') {\n\t\thost, portText, err = net.SplitHostPort(portText)\n\t\tif err != nil {\n\t\t\treturn api.ServeOptions{}, nil, err\n\t\t}\n\t}\n\n\t// Parse the port\n\tvar port int64\n\tif portText != \"\" {\n\t\tport, err = strconv.ParseInt(portText, 10, 32)\n\t\tif err != nil {\n\t\t\treturn api.ServeOptions{}, nil, err\n\t\t}\n\t\tif port < 0 || port > 0xFFFF {\n\t\t\treturn api.ServeOptions{}, nil, fmt.Errorf(\"Invalid port number: %s\", portText)\n\t\t}\n\t\tif port == 0 {\n\t\t\t// 0 is the default value in Go, which we interpret as \"try to\n\t\t\t// pick port 8000\". So Go uses -1 as the sentinel value instead.\n\t\t\tport = -1\n\t\t}\n\t}\n\n\treturn api.ServeOptions{\n\t\tPort:     int(port),\n\t\tHost:     host,\n\t\tServedir: servedir,\n\t\tKeyfile:  keyfile,\n\t\tCertfile: certfile,\n\t\tFallback: fallback,\n\t\tCORS: api.CORSOptions{\n\t\t\tOrigin: corsOrigin,\n\t\t},","sourceCodeStart":1457,"sourceCodeEnd":1493,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/pkg/cli/cli_impl.go#L1457-L1493","documentation":"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.","triggerScenarios":"Running the esbuild CLI with --serve=99999, --serve=-1, or a port value from an environment variable that is out of the valid range.","commonSituations":"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).","solutions":["Use a port number between 0 and 65535 (0 means try port 8000)","Validate the port from environment variables before passing to esbuild CLI","Check for common typos like extra digits or negative signs"],"exampleFix":"# before\nesbuild --serve=99999\n# after\nesbuild --serve=8000","handlingStrategy":"validation","validationCode":"function validatePort(portStr) {\n  const port = parseInt(portStr, 10)\n  if (isNaN(port) || port < 0 || port > 65535) {\n    throw new Error(`Port must be between 0 and 65535, got: ${portStr}`)\n  }\n  return port === 0 ? 8000 : port // esbuild uses 8000 as default for port 0\n}\nconst port = validatePort(process.env.PORT || '8000')\n// then: esbuild --serve=${port}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate port numbers from environment variables before passing to CLI","Restrict port values to the 0-65535 range","Use port 0 to let esbuild auto-select from 8000"],"tags":["esbuild","cli","serve","port","config"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}