slackhq/nebula · warning

ErrBadDetailsVpnAddr

ErrBadDetailsVpnAddr

Error message

invalid packet, malformed detailsVpnAddr

What it means

ErrBadDetailsVpnAddr (lighthouse.go) is returned when parsing a detailsVpnAddr field from a lighthouse reply/packet fails because the byte encoding is malformed — the address bytes don't form a valid netip.Addr for the expected certificate version.

Source

Thrown at lighthouse.go:27

	"net"
	"net/netip"
	"slices"
	"strconv"
	"sync"
	"sync/atomic"
	"time"

	"github.com/gaissmai/bart"
	"github.com/slackhq/nebula/cert"
	"github.com/slackhq/nebula/config"
	"github.com/slackhq/nebula/header"
	"github.com/slackhq/nebula/logging"
	"github.com/slackhq/nebula/udp"
	"github.com/slackhq/nebula/util"
)

var ErrHostNotKnown = errors.New("host not known")
var ErrBadDetailsVpnAddr = errors.New("invalid packet, malformed detailsVpnAddr")

type LightHouse struct {
	//TODO: We need a timer wheel to kick out vpnAddrs that haven't reported in a long time
	sync.RWMutex //Because we concurrently read and write to our maps
	ctx          context.Context
	amLighthouse bool

	myVpnNetworks      []netip.Prefix
	myVpnNetworksTable *bart.Lite
	punchy             *Punchy

	// localAddrsFn enumerates the underlay addresses we advertise. It is a field so tests can supply simulated
	// addresses rather than whatever this machine's NICs happen to be. Set it before Start.
	localAddrsFn func(*LocalAllowList) []netip.Addr

	// Local cache of answers from light houses
	// map of vpn addr to answers
	addrMap map[netip.Addr]*RemoteList

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Upgrade all lighthouses and peers to a matching nebula version
2. Check for packet corruption (NIC offload, MTU) in the path
3. If building packets yourself, encode the vpn addr with the same format/length nebula expects
4. Enable debug logging to dump the offending packet and compare with a healthy lighthouse answer

// validate encoded addr byte length before sending/accepting detailsVpnAddr
if len(rawAddrBytes) != expectedAddrLen(certVersion) {
    // reject malformed detailsVpnAddr
}

func validDetailsVpnAddr(a netip.Addr, version cert.Version) bool {
    return a.IsValid() && !a.IsZero() && addrLenMatchesVersion(a, version)
}

addr, version, err := parseDetailsVpnAddr(raw)
if errors.Is(err, ErrBadDetailsVpnAddr) {
    // drop packet / log and skip this lighthouse answer
    return
}

When it happens

Trigger: A lighthouse answer/upgrade packet contains a detailsVpnAddr whose encoded bytes are the wrong length or format; the v1 fallback parse path fails and returns this error (lighthouse.go:1541).

Common situations: Mixed nebula versions (v1 vs v2 certificate/address encoding) on the mesh; corrupted or tampered lighthouse packets; buggy custom message construction.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• ErrIPv6CouldNotFindPayload
• ErrHostNotKnown
• unable to find host
• unable to find host with relay
• no outside connection

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