{"record":{"id":"03ae1f753c99a883","repo":"nats-io/nats-server","slug":"could-not-parse-port-q","errorCode":null,"errorMessage":"could not parse port %q","messagePattern":"could not parse port %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/opts.go","lineNumber":2008,"sourceCode":"\thost string\n\tport int\n}\n\n// parseListen will parse listen option which is replacing host/net and port\nfunc parseListen(v any) (*hostPort, error) {\n\thp := &hostPort{}\n\tswitch vv := v.(type) {\n\t// Only a port\n\tcase int64:\n\t\thp.port = int(vv)\n\tcase string:\n\t\thost, port, err := net.SplitHostPort(vv)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"could not parse address string %q\", vv)\n\t\t}\n\t\thp.port, err = strconv.Atoi(port)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"could not parse port %q\", port)\n\t\t}\n\t\thp.host = host\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"expected port or host:port, got %T\", vv)\n\t}\n\treturn hp, nil\n}\n\n// parseCluster will parse the cluster config.\nfunc parseCluster(v any, opts *Options, errors *[]error, warnings *[]error) error {\n\tvar lt token\n\tdefer convertPanicToErrorList(&lt, errors)\n\n\ttk, v := unwrapValue(v, &lt)\n\tcm, ok := v.(map[string]any)\n\tif !ok {\n\t\treturn &configErr{tk, fmt.Sprintf(\"Expected map to define cluster, got %T\", v)}\n\t}","sourceCodeStart":1990,"sourceCodeEnd":2026,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/opts.go#L1990-L2026","documentation":"This error is raised by the address-parsing helper in server/opts.go when the host portion split off by net.SplitHostPort is not a valid integer. The port substring exists but strconv.Atoi rejects it, so the library returns this error instead of proceeding with an unusable port.","triggerScenarios":"Config address strings like 'host:4222x', 'host:-1', or 'host: 4222' (embedded space) where SplitHostPort succeeds but Atoi fails on the port part.","commonSituations":"Typos in the port number; units accidentally included ('host:4222/tcp'); env interpolation producing an empty or non-numeric port ('host:${PORT}' with PORT unset); negative or oversized values.","solutions":["Set the port to a plain decimal integer within 1–65535, e.g. '0.0.0.0:4222'.","Check env interpolation: ensure ${PORT} is actually set and numeric in the server's environment.","Strip any protocol suffix or whitespace from the port portion.","Use the offending %q value from the error to see exactly what Atoi received."],"exampleFix":"// before\nlisten: 0.0.0.0:${PORT}  # PORT unset\n// after\nlisten: 0.0.0.0:4222","handlingStrategy":"validation","validationCode":"_, port, err := net.SplitHostPort(addr)\nif err != nil {\n\treturn err\n}\nif n, aerr := strconv.Atoi(port); aerr != nil || n < 1 || n > 65535 {\n\treturn fmt.Errorf(\"invalid port %q in %q\", port, addr)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep ports as plain decimal integers.","Verify env variables used in ports are set and numeric.","Strip protocol suffixes like /tcp from port values."],"tags":["config","port","parsing"],"backgroundTag":"invalid-port-number","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}