nsqio/nsq · error

--node-id must be [0,1024)

Error message

--node-id must be [0,1024)

What it means

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.

Source

Thrown at nsqd/nsqd.go:116

	httpcli := http_api.NewClient(nil, opts.HTTPClientConnectTimeout, opts.HTTPClientRequestTimeout)
	n.ci = clusterinfo.New(n.logf, httpcli)

	n.lookupPeers.Store([]*lookupPeer{})

	n.swapOpts(opts)
	n.errValue.Store(errStore{})

	err = n.dl.Lock()
	if err != nil {
		return nil, fmt.Errorf("failed to lock data-path: %v", err)
	}

	if opts.MaxDeflateLevel < 1 || opts.MaxDeflateLevel > 9 {
		return nil, errors.New("--max-deflate-level must be [1,9]")
	}

	if opts.ID < 0 || opts.ID >= 1024 {
		return nil, errors.New("--node-id must be [0,1024)")
	}

	if opts.TLSClientAuthPolicy != "" && opts.TLSRequired == TLSNotRequired {
		opts.TLSRequired = TLSRequired
	}

	tlsConfig, err := buildTLSConfig(opts)
	if err != nil {
		return nil, fmt.Errorf("failed to build TLS config - %s", err)
	}
	if tlsConfig == nil && opts.TLSRequired != TLSNotRequired {
		return nil, errors.New("cannot require TLS client connections without TLS key and cert")
	}
	n.tlsConfig = tlsConfig

	clientTLSConfig, err := buildClientTLSConfig(opts)
	if err != nil {
		return nil, fmt.Errorf("failed to build client TLS config - %s", err)

View on GitHub (pinned to 85cf10c09c)

Solutions

1. Choose a unique integer in [0,1024) per nsqd, e.g. --node-id=7.
2. Allocate ids from a small config registry or derive deterministically from a host index when running many nodes.
3. 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.

Example fix

# before
nsqd --node-id=1024
# after
nsqd --node-id=7

if opts.ID < 0 || opts.ID >= 1024 {
	return fmt.Errorf("invalid node-id %d: must be in [0,1024) and unique per cluster", opts.ID)
}
_, err := nsqd.New(opts)

When it happens

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

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

Related errors

• --max-deflate-level must be [1,9]
• cannot require TLS client connections without TLS key and ce
• --auth-http-request-method must be post or get
• address should not contain scheme
• missing <REV> in --filename-format when gzip, rotation, or w

AI-assisted analysis of nsqio/nsq@85cf10c09c (2026-08-16). Data as JSON: /api/errors/274e56f0b2550cd2. Report an issue: GitHub.