slackhq/nebula · critical

failed to generate unique localIndexId

Error message

failed to generate unique localIndexId

What it means

A non-sentinel error raised by HandshakeManager.allocateIndex when, after scanning candidate index values, it cannot find a localIndexId that is free in the indexes map. Means the local index space is effectively exhausted or heavily contended.

Source

Thrown at handshake_manager.go:527

	defer hm.Unlock()

	for range 32 {
		index, err := generateIndex(hm.l)
		if err != nil {
			return 0, err
		}

		_, inPending := hm.indexes[index]
		_, inMain := hm.mainHostMap.Indexes[index]

		if !inMain && !inPending {
			hh.hostinfo.localIndexId = index
			hm.indexes[index] = hh
			return index, nil
		}
	}

	return 0, errors.New("failed to generate unique localIndexId")
}

func (hm *HandshakeManager) DeleteHostInfo(hostinfo *HostInfo) {
	hm.Lock()
	defer hm.Unlock()
	hm.unlockedDeleteHostInfo(hostinfo)
}

func (hm *HandshakeManager) unlockedDeleteHostInfo(hostinfo *HostInfo) {
	for _, addr := range hostinfo.vpnAddrs {
		if cur, ok := hm.vpnIps[addr]; ok && cur.hostinfo == hostinfo {
			delete(hm.vpnIps, addr)
		}
	}

	if len(hm.vpnIps) == 0 {
		hm.vpnIps = map[netip.Addr]*HandshakeHostInfo{}
	}

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Investigate and fix hostinfo/index leaks — ensure DeleteHostInfo is called when connections close
2. Restart or recycle the process to clear a saturated index map
3. Reduce handshake churn (fix flapping peers, aggressive reconnect timers) that fills the index space

if len(hm.indexes) >= maxIndexes-1 {
    return fmt.Errorf("index map nearly exhausted")
}

index, err := hm.allocateIndex(hh)
if err != nil {
    // cannot allocate: shed load / fail handshake; retry with backoff
    return err
}

When it happens

Trigger: allocateIndex (handshake_manager.go:527) iterating candidate indices finds every candidate already present in hm.indexes, so it returns errors.New("failed to generate unique localIndexId").

Common situations: Index map leak — hostinfos never deleted via DeleteHostInfo so indexes accumulate; a massive handshake storm; a 32-bit/limited index space saturated by very long uptime with many peers.

Related errors

• %w: %w
• ErrIndexAllocation
• ErrNoPeerStaticKey
• ErrNoPayload
• ErrInitiateOnResponder

AI-assisted analysis of slackhq/nebula@dd8f660c0a (2026-09-03). Data as JSON: /api/errors/451fa0fb0c5c3490. Report an issue: GitHub.