slackhq/nebula · error

ErrUnknownSubtype

ErrUnknownSubtype

Error message

%w: %d

What it means

Returned by subtypeInfoFor when a header.MessageSubType has no registered entry in subtypeInfos. Each handshake message subtype must have a known pattern/role mapping; an unknown numeric subtype cannot be processed.

Source

Thrown at handshake/patterns.go:53

	// XX: 3 messages
	//   msg1 (I->R): payload only
	//   msg2 (R->I): payload + cert
	//   msg3 (I->R): cert only
	//header.HandshakeXXPSK0: {
	//	pattern: noise.HandshakeXX,
	//	msgs: []msgFlags{
	//		{expectsPayload: true, expectsCert: false},
	//		{expectsPayload: true, expectsCert: true},
	//		{expectsPayload: false, expectsCert: true},
	//	},
	//},
}

func subtypeInfoFor(subtype header.MessageSubType) (subtypeInfo, error) {
	if info, ok := subtypeInfos[subtype]; ok {
		return info, nil
	}
	return subtypeInfo{}, fmt.Errorf("%w: %d", ErrUnknownSubtype, subtype)
}

View on GitHub (pinned to dd8f660c0a)

Solutions

  1. Upgrade the node so its subtypeInfos includes the subtype used by peers
  2. Use only supported header.MessageSubType constants when constructing machines
  3. Check peers' nebula versions for protocol skew
Defensive patterns

Strategy: type-guard

Validate before calling

if _, ok := subtypeInfos[subType]; !ok {
    return fmt.Errorf("unsupported handshake subtype %d on this node version", subType)
}

Type guard

func knownSubtype(s header.MessageSubType) bool {
    _, ok := subtypeInfos[s]
    return ok
}

Prevention

When it happens

Trigger: Calling NewMachine (or the anonymous caller) with a MessageSubType value that is not in the subtypeInfos map — e.g. a subtype constant from a newer nebula version not known to this build.

Common situations: Mixed-version clusters where a newer node sends a handshake subtype the older node doesn't recognize; typo'd or custom subtype passed programmatically.

Related errors

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