{"record":{"id":"ec0f55cb8b5306ba","repo":"slackhq/nebula","slug":"errhostnotknown","errorCode":"ErrHostNotKnown","errorMessage":"host not known","messagePattern":"host not known","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"lighthouse.go","lineNumber":26,"sourceCode":"\t\"log/slog\"\n\t\"net\"\n\t\"net/netip\"\n\t\"slices\"\n\t\"strconv\"\n\t\"sync\"\n\t\"sync/atomic\"\n\t\"time\"\n\n\t\"github.com/gaissmai/bart\"\n\t\"github.com/slackhq/nebula/cert\"\n\t\"github.com/slackhq/nebula/config\"\n\t\"github.com/slackhq/nebula/header\"\n\t\"github.com/slackhq/nebula/logging\"\n\t\"github.com/slackhq/nebula/udp\"\n\t\"github.com/slackhq/nebula/util\"\n)\n\nvar ErrHostNotKnown = errors.New(\"host not known\")\nvar ErrBadDetailsVpnAddr = errors.New(\"invalid packet, malformed detailsVpnAddr\")\n\ntype LightHouse struct {\n\t//TODO: We need a timer wheel to kick out vpnAddrs that haven't reported in a long time\n\tsync.RWMutex //Because we concurrently read and write to our maps\n\tctx          context.Context\n\tamLighthouse bool\n\n\tmyVpnNetworks      []netip.Prefix\n\tmyVpnNetworksTable *bart.Lite\n\tpunchy             *Punchy\n\n\t// localAddrsFn enumerates the underlay addresses we advertise. It is a field so tests can supply simulated\n\t// addresses rather than whatever this machine's NICs happen to be. Set it before Start.\n\tlocalAddrsFn func(*LocalAllowList) []netip.Addr\n\n\t// Local cache of answers from light houses\n\t// map of vpn addr to answers","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/lighthouse.go#L8-L44","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the target IP is correct and inside the certificate's VPN networks","Ensure the target host can reach the lighthouse and has completed a handshake","Check static_host_map entries for hosts that must be reachable before handshake","Wait/retry after startup so lighthouses have learned the host"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// only query the lighthouse for IPs you know are in the mesh\nif !vpnNetworks.Contains(targetIp) {\n    // skip: IP is outside all certificate vpn networks\n}","typeGuard":null,"tryCatchPattern":"addr, err := lh.QueryVpnIP(targetIp)\nif errors.Is(err, ErrHostNotKnown) {\n    // trigger host query/handshake and retry after a short delay\n}","preventionTips":["Use static_host_map for peers that must be reachable immediately","Ensure peers can reach lighthouses so their IPs get learned","Confirm target IPs match the certificate's vpn networks","Allow a grace period after startup before querying hosts"],"tags":["network","lighthouse","discovery","nebula"],"backgroundTag":"host-not-known","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"}