ErrMultiMessageUnsupported

ErrMultiMessageUnsupported

Error message

multi-message handshake patterns are not yet supported by the manager

What it means

ErrMultiMessageUnsupported indicates the handshake manager received a handshake whose Noise pattern requires multiple messages (e.g. XX or multi-stage patterns), which the manager does not implement. Only single-message IX-style handshake patterns are supported. The manager logs the error and abandons the handshake instead of attempting it.

Source

Thrown at handshake/errors.go:20

import "errors"

var (
	ErrInitiateOnResponder     = errors.New("initiate called on responder")
	ErrInitiateAlreadyCalled   = errors.New("initiate already called")
	ErrInitiateNotCalled       = errors.New("initiate must be called before ProcessPacket for initiators")
	ErrPacketTooShort          = errors.New("packet too short")
	ErrPublicKeyMismatch       = errors.New("public key mismatch between certificate and handshake")
	ErrIncompleteHandshake     = errors.New("handshake completed without receiving required content")
	ErrMachineFailed           = errors.New("handshake machine has failed")
	ErrUnknownSubtype          = errors.New("unknown handshake subtype")
	ErrMissingContent          = errors.New("expected handshake content but message was empty")
	ErrUnexpectedContent       = errors.New("received unexpected handshake content")
	ErrInvalidRemoteIndex      = errors.New("peer sent an invalid index in handshake payload")
	ErrIndexAllocation         = errors.New("failed to allocate local index")
	ErrNoCredential            = errors.New("no handshake credential available for cert version")
	ErrAsymmetricCipherKeys    = errors.New("noise produced only one cipher key")
	ErrMultiMessageUnsupported = errors.New("multi-message handshake patterns are not yet supported by the manager")
	ErrSubtypeMismatch         = errors.New("packet subtype does not match handshake machine subtype")
)

View on GitHub (pinned to dd8f660c0a)

Solutions

Change the handshake pattern configuration to a supported single-message pattern (IX/IX-PSK style)
Ensure both peers run versions/configs that agree on the supported handshake pattern
If multi-message support is required, update the library or extend the manager, since it is explicitly not yet implemented

Example fix

// before (config)
handshake:
  pattern: xx_psk0
// after
handshake:
  pattern: ix_psk0

Defensive patterns

Strategy: validation

Validate before calling

if !supportedPatterns[pattern] {
    return fmt.Errorf("handshake pattern %v unsupported by manager: %w", pattern, handshake.ErrMultiMessageUnsupported)
}

Try / catch

_, err := beginHandshake(...)
if errors.Is(err, handshake.ErrMultiMessageUnsupported) {
    // log and abandon; do not retry — it cannot succeed
    return
}

Prevention

Configure only IX-style single-message handshake patterns
Keep both peers on configs/versions with matching pattern support
Fail fast at config-load time if an unsupported pattern is set

When it happens

Trigger: Calling beginHandshake (or a peer initiating one) with a handshake pattern configured to a multi-message pattern; the manager's responder path detects it at handshake_manager.go:736 and logs 'multi-message handshake responder is not supported'.

Common situations: Mixing node versions or configs where one side uses an XX/PSK multi-message pattern while the manager only supports IX-style; copying a cipher/handshake config from another Nebula-like deployment; upgrading tunnel configs without checking handshake pattern support.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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