{"record":{"id":"e0cbcc126fb50576","repo":"netbirdio/netbird","slug":"create-forwarder-w","errorCode":null,"errorMessage":"create forwarder: %w","messagePattern":"create forwarder: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/firewall/uspfilter/filter.go","lineNumber":485,"sourceCode":"}\n\n// initForwarder initializes the forwarder, it disables routing on errors\nfunc (m *Manager) initForwarder() error {\n\tif m.forwarder.Load() != nil {\n\t\treturn nil\n\t}\n\n\t// Only supported in userspace mode as we need to inject packets back into wireguard directly\n\tintf := m.wgIface.GetWGDevice()\n\tif intf == nil {\n\t\tm.routingEnabled.Store(false)\n\t\treturn errors.New(\"forwarding not supported\")\n\t}\n\n\tforwarder, err := forwarder.New(m.wgIface, m.logger, m.flowLogger, m.netstack, m.mtu)\n\tif err != nil {\n\t\tm.routingEnabled.Store(false)\n\t\treturn fmt.Errorf(\"create forwarder: %w\", err)\n\t}\n\n\tm.forwarder.Store(forwarder)\n\n\t// Re-load after store: a concurrent SetPacketCapture may have seen forwarder as nil and only updated pendingCapture.\n\tif pc := m.pendingCapture.Load(); pc != nil {\n\t\tforwarder.SetCapture(*pc)\n\t}\n\n\tlog.Debug(\"forwarder initialized\")\n\n\treturn nil\n}\n\nfunc (m *Manager) Init(*statemanager.Manager) error {\n\treturn nil\n}\n","sourceCodeStart":467,"sourceCodeEnd":503,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/firewall/uspfilter/filter.go#L467-L503","documentation":"Returned by initForwarder (client/firewall/uspfilter/filter.go:485) when forwarder.New fails while building the gVisor netstack forwarder. By then GetWGDevice() was non-nil; failure comes from inside the forwarder package - stack options, CreateNIC ('create NIC: %v'), AddProtocolAddress, or listener setup. On failure routingEnabled is set false, so userspace routing (exit nodes, network routes) is disabled for the session even though the manager survives.","triggerScenarios":"EnableRouting in userspace mode with an interface whose address is unset/invalid (forwarder.New's protocol-address setup fails); MTU of 0 or absurd values passed through; netstack mode where the device endpoint cannot attach; gVisor stack resource exhaustion (memory/nicoleg) on constrained hosts.","commonSituations":"Enabling routing before the interface is fully configured; embedded/wasm builds where netstack initialization differs; very low-memory containers failing gVisor allocation; MTU misconfiguration via flags or management.","solutions":["Ensure the interface is up with valid v4 (and optional v6) addresses and a sane MTU before EnableRouting","Retry EnableRouting once after bring-up completes; initForwarder is guarded to run only when the forwarder is nil","Check logs for the wrapped inner error (create NIC / add protocol address) to pinpoint the failing setup step","If userspace routing cannot be supported in this environment, run with EnvDisableUserspaceRouting so routing falls through without the forwarder"],"exampleFix":"// before\nforwarder, err := forwarder.New(m.wgIface, m.logger, m.flowLogger, m.netstack, m.mtu)\nif err != nil {\n    m.routingEnabled.Store(false)\n    return fmt.Errorf(\"create forwarder: %w\", err)\n}\n// after\nif !m.wgIface.Address().IP.IsValid() || m.mtu == 0 {\n    m.routingEnabled.Store(false)\n    return fmt.Errorf(\"create forwarder: iface address or MTU not ready\")\n}\nforwarder, err := forwarder.New(m.wgIface, m.logger, m.flowLogger, m.netstack, m.mtu)\nif err != nil {\n    m.routingEnabled.Store(false)\n    return fmt.Errorf(\"create forwarder: %w\", err)\n}","handlingStrategy":"retry","validationCode":"if !wgIface.Address().IP.IsValid() || mtu < 576 {\n    return fmt.Errorf(\"forwarder prerequisites unmet (addr=%s mtu=%d)\", wgIface.Address().IP, mtu)\n}\n_ = fw.EnableRouting()","typeGuard":"func forwarderPrereqsMet(i common.IFaceMapper, mtu int) bool {\n    return i.GetWGDevice() != nil && i.Address().IP.IsValid() && mtu >= 576\n}","tryCatchPattern":"if err := fw.EnableRouting(); err != nil {\n    if strings.Contains(err.Error(), \"create forwarder\") || strings.Contains(err.Error(), \"determine routing\") {\n        // routing degraded, overlay still works; retry after bring-up\n        scheduleRoutingRetry()\n        return nil\n    }\n    return err\n}","preventionTips":["Bring the interface fully up (address, MTU) before EnableRouting","initForwarder disables routing on error - re-run EnableRouting once state settles","Check for the wrapped create NIC / protocol-address messages to find the real prerequisite that failed"],"tags":["uspfilter","forwarder","netstack","gvisor","routing"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}