{"record":{"id":"a0178a784088a24b","repo":"tailscale/tailscale","slug":"installing-rule-for-forwarding-traffic-to-tailnet","errorCode":null,"errorMessage":"installing rule for forwarding traffic to tailnet IP: %w","messagePattern":"installing rule for forwarding traffic to tailnet IP: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/containerboot/forwarding.go","lineNumber":153,"sourceCode":"\tif err != nil {\n\t\treturn err\n\t}\n\tvar local netip.Addr\n\tfor _, pfx := range tsIPs {\n\t\tif !pfx.IsSingleIP() {\n\t\t\tcontinue\n\t\t}\n\t\tif pfx.Addr().Is4() != dst.Is4() {\n\t\t\tcontinue\n\t\t}\n\t\tlocal = pfx.Addr()\n\t\tbreak\n\t}\n\tif !local.IsValid() {\n\t\treturn fmt.Errorf(\"no tailscale IP matching family of %s found in %v\", dstFilter, tsIPs)\n\t}\n\tif err := nfr.AddDNATRule(dst, local); err != nil {\n\t\treturn fmt.Errorf(\"installing rule for forwarding traffic to tailnet IP: %w\", err)\n\t}\n\treturn nil\n}\n\nfunc installIngressForwardingRule(_ context.Context, dstStr string, tsIPs []netip.Prefix, nfr linuxfw.NetfilterRunner) error {\n\tdst, err := netip.ParseAddr(dstStr)\n\tif err != nil {\n\t\treturn err\n\t}\n\tvar local netip.Addr\n\tproxyHasIPv4Address := false\n\tfor _, pfx := range tsIPs {\n\t\tif !pfx.IsSingleIP() {\n\t\t\tcontinue\n\t\t}\n\t\tif pfx.Addr().Is4() {\n\t\t\tproxyHasIPv4Address = true\n\t\t}","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/tailscale/tailscale/blob/cfe32b8be6a33f8e24fbc369cbfbf7c729d9e042/cmd/containerboot/forwarding.go#L135-L171","documentation":"Thrown by installTSForwardingRuleForDestination when nfr.AddDNATRule(dst, local) fails — the DNAT rule that maps the cluster destination address to the family-matched tailnet IP could not be programmed. As with all NetfilterRunner failures, the wrapped error comes from the iptables or nftables backend and typically indicates missing capabilities, absent tooling, or an unsupported firewall mode.","triggerScenarios":"Container without CAP_NET_ADMIN/privileged; iptables or nftables binaries and kernel modules missing from image/host; TS_DEBUG_FIREWALL_MODE auto-detection selecting a mode the kernel does not support; netfilter tables locked by another process.","commonSituations":"Operator proxies deployed with restricted securityContext; distroless images without firewall tools; hosts with nftables-only kernels and an iptables-mode runner.","solutions":["Run the proxy with CAP_NET_ADMIN or privileged","Install/verify iptables and nftables in the image and their modules on the host","Pin TS_DEBUG_FIREWALL_MODE to the stack the host actually supports","Read the wrapped error for the failing backend command and remediate that"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := nfr.AddDNATRule(dst, local); err != nil {\n    var ee *exec.ExitError\n    if errors.As(err, &ee) {\n        log.Printf(\"netfilter stderr: %s\", ee.Stderr)\n    }\n    return fmt.Errorf(\"installing rule for forwarding traffic to tailnet IP: %w\", err)\n}","preventionTips":["Run with CAP_NET_ADMIN/privileged","Verify firewall binaries and modules in image and host","Pin the firewall mode explicitly for predictable backend selection"],"tags":["netfilter","dnat","net-admin","forwarding","iptables"],"backgroundTag":null,"analyzedSha":"cfe32b8be6a33f8e24fbc369cbfbf7c729d9e042","analyzedAt":"2026-08-15T19:58:31.583Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}