slackhq/nebula · error

invalid handshake details

Error message

invalid handshake details

What it means

errInvalidHandshakeDetails is returned by unmarshalPayloadDetails when the details sub-message inside a handshake payload is malformed: either protowire.ConsumeTag fails, or a field (e.g. fieldCert) has the wrong wire type (not BytesType). The outer tag parsed but the nested details did not.

Source

Thrown at handshake/payload.go:12

package handshake

import (
	"errors"
	"math"

	"google.golang.org/protobuf/encoding/protowire"
)

var (
	errInvalidHandshakeMessage = errors.New("invalid handshake message")
	errInvalidHandshakeDetails = errors.New("invalid handshake details")
)

// Payload represents the decoded fields of a handshake message.
// Wire format is protobuf-compatible with NebulaHandshake{Details: NebulaHandshakeDetails{...}}.
type Payload struct {
	Cert           []byte
	InitiatorIndex uint32
	ResponderIndex uint32
	Time           uint64
	CertVersion    uint32
}

// Proto field numbers for NebulaHandshakeDetails
const (
	fieldCert           = 1 // bytes
	fieldInitiatorIndex = 2 // uint32
	fieldResponderIndex = 3 // uint32
	fieldTime           = 5 // uint64

View on GitHub (pinned to dd8f660c0a)

Solutions

  1. Confirm both peers encode handshake details with the same schema and field numbering
  2. Ensure the certificate field is serialized as a length-delimited (bytes) protobuf field
  3. Regenerate or update the peer software if it is emitting a nonstandard details payload
Defensive patterns

Strategy: try-catch

Validate before calling

if len(b) == 0 {
    return fmt.Errorf("empty handshake details")
}

Try / catch

err := unmarshalPayloadDetails(details, &p)
if errors.Is(err, errInvalidHandshakeDetails) {
    // reject packet with invalid details sub-message
    return err
}

Prevention

When it happens

Trigger: A handshake payload whose Details sub-message is truncated or whose fields use wrong wire types — e.g. fieldCert encoded as varint instead of bytes — passed through UnmarshalPayload.

Common situations: Hand-crafted or fuzzed handshake packets; a peer with a different schema version encoding fields differently; corruption localized to the details sub-message.

Understand the failure class

Related errors

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