{"record":{"id":"db314b20562d4e01","repo":"slackhq/nebula","slug":"errunknownsubtype","errorCode":"ErrUnknownSubtype","errorMessage":"unknown handshake subtype","messagePattern":"unknown handshake subtype","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"handshake/errors.go","lineNumber":13,"sourceCode":"package handshake\n\nimport \"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":1,"sourceCodeEnd":23,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/handshake/errors.go#L1-L23","documentation":"ErrUnknownSubtype is returned by subtypeInfoFor when asked for pattern info for a handshake subtype number that this build does not know. It indicates a protocol negotiation mismatch: the peer referenced a handshake pattern variant that is not registered locally. The error is wrapped with the offending subtype number via fmt.Errorf.","triggerScenarios":"subtypeInfoFor(99) in handshake/patterns.go:53 has no entry for the given subtype byte from an incoming packet's header; covered by patterns_test.go:45.","commonSituations":"Peer runs a newer/older library version supporting additional handshake subtypes; a corrupted or attacker-crafted packet carries a bogus subtype byte; misconfigured listeners speaking a different pattern variant.","solutions":["Upgrade this library so both peers support the same set of handshake subtypes","Pin both deployments to a version with matching pattern tables","If the packet is unexpected or untrusted, drop the connection and log the peer address"],"exampleFix":"// before: peer negotiated subtype 99 (unsupported here)\n// after: align versions and configure both peers to an agreed subtype\n$ go get github.com/example/mesh@v1.9.0 // adds subtype 99 support\n// or configure peer to use subtype 1 (XX-like pattern)","handlingStrategy":"validation","validationCode":"if _, err := handshake.SubtypeInfoFor(subtype); err != nil {\n    // reject or negotiate down before starting the handshake\n    return fmt.Errorf(\"peer requested unsupported subtype %d\", subtype)\n}","typeGuard":"func subtypeSupported(subtype byte) bool {\n    _, err := handshake.SubtypeInfoFor(subtype)\n    return err == nil\n}","tryCatchPattern":"info, err := handshake.SubtypeInfoFor(hdr.Subtype)\nif errors.Is(err, handshake.ErrUnknownSubtype) {\n    conn.Close()\n    log.Printf(\"unsupported handshake subtype %d from %s\", hdr.Subtype, conn.RemoteAddr())\n    return\n}","preventionTips":["Pin all nodes to library versions supporting the same subtype set","Negotiate the highest mutually supported subtype before handshaking","Alert on unknown subtype hits — likely version skew or hostile traffic"],"tags":["handshake","protocol","versioning"],"backgroundTag":"unsupported-protocol-subtype","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"}