{"record":{"id":"274e56f0b2550cd2","repo":"nsqio/nsq","slug":"node-id-must-be-0-1024","errorCode":null,"errorMessage":"--node-id must be [0,1024)","messagePattern":"--node-id must be \\[0,1024\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nsqd/nsqd.go","lineNumber":116,"sourceCode":"\thttpcli := http_api.NewClient(nil, opts.HTTPClientConnectTimeout, opts.HTTPClientRequestTimeout)\n\tn.ci = clusterinfo.New(n.logf, httpcli)\n\n\tn.lookupPeers.Store([]*lookupPeer{})\n\n\tn.swapOpts(opts)\n\tn.errValue.Store(errStore{})\n\n\terr = n.dl.Lock()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to lock data-path: %v\", err)\n\t}\n\n\tif opts.MaxDeflateLevel < 1 || opts.MaxDeflateLevel > 9 {\n\t\treturn nil, errors.New(\"--max-deflate-level must be [1,9]\")\n\t}\n\n\tif opts.ID < 0 || opts.ID >= 1024 {\n\t\treturn nil, errors.New(\"--node-id must be [0,1024)\")\n\t}\n\n\tif opts.TLSClientAuthPolicy != \"\" && opts.TLSRequired == TLSNotRequired {\n\t\topts.TLSRequired = TLSRequired\n\t}\n\n\ttlsConfig, err := buildTLSConfig(opts)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to build TLS config - %s\", err)\n\t}\n\tif tlsConfig == nil && opts.TLSRequired != TLSNotRequired {\n\t\treturn nil, errors.New(\"cannot require TLS client connections without TLS key and cert\")\n\t}\n\tn.tlsConfig = tlsConfig\n\n\tclientTLSConfig, err := buildClientTLSConfig(opts)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to build client TLS config - %s\", err)","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/nsqio/nsq/blob/85cf10c09c6c3c86160d6f0eb156f62d0efc1648/nsqd/nsqd.go#L98-L134","documentation":"nsqd embeds a node identifier in every message ID it generates (guid = node id + timestamp + counter), reserving 10 bits for it. nsqd.New therefore requires opts.ID (--node-id) in [0,1024); negative values or >= 1024 abort startup. Every node publishing into a cluster must use a distinct id or IDs from different nodes can collide.","triggerScenarios":"Starting nsqd with --node-id=1024, --node-id=-1, or any value outside 0..1023. The guard is opts.ID < 0 || opts.ID >= 1024 immediately after the deflate-level check, so failure is deterministic at construction time.","commonSituations":"Auto-assigning ids from a 1-based scheme that hits 1024 in large fleets; parsing errors in config (empty string -> 0 is fine, garbage -> flag package error); renumbering that briefly produced duplicates/negatives.","solutions":["Choose a unique integer in [0,1024) per nsqd, e.g. --node-id=7.","Allocate ids from a small config registry or derive deterministically from a host index when running many nodes.","If you have more than 1024 logical nodes, shard them across independent clusters - the id space is a hard limit of the message-ID format."],"exampleFix":"# before\nnsqd --node-id=1024\n# after\nnsqd --node-id=7","handlingStrategy":"validation","validationCode":"if opts.ID < 0 || opts.ID >= 1024 {\n\treturn fmt.Errorf(\"invalid node-id %d: must be in [0,1024) and unique per cluster\", opts.ID)\n}\n_, err := nsqd.New(opts)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Allocate node ids from configuration management with uniqueness checks; alert on duplicates.","Treat >1023 as a signal to split into separate NSQ clusters, since the message-ID format cannot encode more."],"tags":["nsq","nsqd","cli","config","message-id"],"backgroundTag":null,"analyzedSha":"85cf10c09c6c3c86160d6f0eb156f62d0efc1648","analyzedAt":"2026-08-16T00:53:05.009Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}