entry %v.via in tun.unsafe_routes failed to parse address: %

Error message

entry %v.via in tun.unsafe_routes failed to parse address: %v

What it means

Config validation error in parseUnsafeRoutes: the `via` key of the i+1-th entry is a string but netip.ParseAddr rejected it as an IP address (e.g. a hostname or malformed IP). The ParseAddr error is included.

Source

Thrown at overlay/route.go:216

			}
		}

		if metric < 0 || metric > math.MaxInt32 {
			return nil, fmt.Errorf("entry %v.metric in tun.unsafe_routes is not in range (0-%d) : %v", i+1, math.MaxInt32, metric)
		}

		rVia, ok := m["via"]
		if !ok {
			return nil, fmt.Errorf("entry %v.via in tun.unsafe_routes is not present", i+1)
		}

		var gateways routing.Gateways

		switch via := rVia.(type) {
		case string:
			viaIp, err := netip.ParseAddr(via)
			if err != nil {
				return nil, fmt.Errorf("entry %v.via in tun.unsafe_routes failed to parse address: %v", i+1, err)
			}

			gateways = routing.Gateways{routing.NewGateway(viaIp, 1)}

		case []any:
			gateways = make(routing.Gateways, len(via))
			for ig, v := range via {
				gatewayMap, ok := v.(map[string]any)
				if !ok {
					return nil, fmt.Errorf("entry %v in tun.unsafe_routes[%v].via is invalid", i+1, ig+1)
				}

				rGateway, ok := gatewayMap["gateway"]
				if !ok {
					return nil, fmt.Errorf("entry .gateway in tun.unsafe_routes[%v].via[%v] is not present", i+1, ig+1)
				}

				parsedGateway, ok := rGateway.(string)

View on GitHub (pinned to dd8f660c0a)

Solutions

Use a literal IP address for via (hostnames are not resolved)
Fix typos in the IP literal

Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at overlay/route.go:216 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

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