{"record":{"id":"1e3f661dca1ecee6","repo":"slackhq/nebula","slug":"errsubtypemismatch","errorCode":"ErrSubtypeMismatch","errorMessage":"packet subtype does not match handshake machine subtype","messagePattern":"packet subtype does not match handshake machine subtype","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"handshake/errors.go","lineNumber":21,"sourceCode":"import \"errors\"\n\nvar (\n\tErrInitiateOnResponder     = errors.New(\"initiate called on responder\")\n\tErrInitiateAlreadyCalled   = errors.New(\"initiate already called\")\n\tErrInitiateNotCalled       = errors.New(\"initiate must be called before ProcessPacket for initiators\")\n\tErrPacketTooShort          = errors.New(\"packet too short\")\n\tErrPublicKeyMismatch       = errors.New(\"public key mismatch between certificate and handshake\")\n\tErrIncompleteHandshake     = errors.New(\"handshake completed without receiving required content\")\n\tErrMachineFailed           = errors.New(\"handshake machine has failed\")\n\tErrUnknownSubtype          = errors.New(\"unknown handshake subtype\")\n\tErrMissingContent          = errors.New(\"expected handshake content but message was empty\")\n\tErrUnexpectedContent       = errors.New(\"received unexpected handshake content\")\n\tErrInvalidRemoteIndex      = errors.New(\"peer sent an invalid index in handshake payload\")\n\tErrIndexAllocation         = errors.New(\"failed to allocate local index\")\n\tErrNoCredential            = errors.New(\"no handshake credential available for cert version\")\n\tErrAsymmetricCipherKeys    = errors.New(\"noise produced only one cipher key\")\n\tErrMultiMessageUnsupported = errors.New(\"multi-message handshake patterns are not yet supported by the manager\")\n\tErrSubtypeMismatch         = errors.New(\"packet subtype does not match handshake machine subtype\")\n)\n","sourceCodeStart":3,"sourceCodeEnd":23,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/handshake/errors.go#L3-L23","documentation":"ErrSubtypeMismatch is returned by ProcessPacket when the packet's MessageSubType byte does not match the subtype the handshake Machine was constructed for. The machine drops the packet without failing, so a legitimate retransmit can still complete later.","triggerScenarios":"Feeding ProcessPacket (handshake/machine.go:216) a handshake packet whose header subtype differs from m.subtype — e.g. an IX PSK0 packet delivered to a machine expecting XX PSK0, or cross-wired UDP ports delivering foreign handshake packets.","commonSituations":"Two nodes configured with different handshake subtypes trying to connect; stray handshake traffic from another tunnel/overlay landing on the same UDP port; misconfigured firewall/port-forward routing handshake packets to the wrong host.","solutions":["Verify both peers configure the same handshake message subtype (e.g. HandshakeIXPSK0 vs HandshakeXXPSK0)","Check that the UDP listener isn't receiving handshake packets from other tunnels or hosts (stray traffic); safe to ignore","Inspect packet[1] in the offending packet to confirm the subtype being sent"],"exampleFix":"// before\nmachine := NewMachine(cs, version, initiator, HandshakeXXPSK0)\n// after (match the peer)\nmachine := NewMachine(cs, version, initiator, HandshakeIXPSK0)","handlingStrategy":"validation","validationCode":"if header.MessageSubType(packet[1]) != expectedSubtype {\n    // drop packet; would cause handshake.ErrSubtypeMismatch\n    return\n}","typeGuard":null,"tryCatchPattern":"_, _, err := m.ProcessPacket(nil, packet)\nif errors.Is(err, handshake.ErrSubtypeMismatch) {\n    // safe to ignore: machine is not killed, legit retransmits still work\n    return\n}","preventionTips":["Use identical handshake subtype config on both peers","Filter stray handshake traffic on shared UDP ports","Never hardcode subtype bytes; use header constants"],"tags":["handshake","subtype","packet-parsing"],"backgroundTag":"handshake-subtype-mismatch","analyzedSha":"dd8f660c0ac37903ec4080ca4d3c861ba9342ceb","analyzedAt":"2026-09-03T11:13:55.444Z","contentChangedAt":"2026-09-03T11:13:55.444Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}