slackhq/nebula · error

ErrHostNotKnown

ErrHostNotKnown

Error message

host not known

What it means

ErrHostNotKnown (lighthouse.go) is returned by lighthouse lookup code when a queried VPN address has no known host entry — the lighthouse has never learned (or has forgotten) address details for that overlay IP.

Source

Thrown at lighthouse.go:26

	"log/slog"
	"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

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Verify the target IP is correct and inside the certificate's VPN networks
2. Ensure the target host can reach the lighthouse and has completed a handshake
3. Check static_host_map entries for hosts that must be reachable before handshake
4. Wait/retry after startup so lighthouses have learned the host

// only query the lighthouse for IPs you know are in the mesh
if !vpnNetworks.Contains(targetIp) {
    // skip: IP is outside all certificate vpn networks
}

addr, err := lh.QueryVpnIP(targetIp)
if errors.Is(err, ErrHostNotKnown) {
    // trigger host query/handshake and retry after a short delay
}

When it happens

Trigger: Querying the LightHouse for a vpn addr with no cached host info; a peer requests remote addresses for an IP the lighthouse doesn't know; entry aged out of the lighthouse map.

Common situations: Target host is offline or never connected; wrong VPN CIDR/IP in handshakes or static host_map entries; lighthouse not yet learned the host (startup race); stale references after host re-IP.

Related errors

• ErrBadDetailsVpnAddr
• unable to find host
• unable to find host with relay
• no outside connection
• no inside interface (tun)

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