tailscale/tailscale · error

installing rule for forwarding traffic to tailnet IP: %w

Error message

installing rule for forwarding traffic to tailnet IP: %w

What it means

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.

Source

Thrown at cmd/containerboot/forwarding.go:153

	if err != nil {
		return err
	}
	var local netip.Addr
	for _, pfx := range tsIPs {
		if !pfx.IsSingleIP() {
			continue
		}
		if pfx.Addr().Is4() != dst.Is4() {
			continue
		}
		local = pfx.Addr()
		break
	}
	if !local.IsValid() {
		return fmt.Errorf("no tailscale IP matching family of %s found in %v", dstFilter, tsIPs)
	}
	if err := nfr.AddDNATRule(dst, local); err != nil {
		return fmt.Errorf("installing rule for forwarding traffic to tailnet IP: %w", err)
	}
	return nil
}

func installIngressForwardingRule(_ context.Context, dstStr string, tsIPs []netip.Prefix, nfr linuxfw.NetfilterRunner) error {
	dst, err := netip.ParseAddr(dstStr)
	if err != nil {
		return err
	}
	var local netip.Addr
	proxyHasIPv4Address := false
	for _, pfx := range tsIPs {
		if !pfx.IsSingleIP() {
			continue
		}
		if pfx.Addr().Is4() {
			proxyHasIPv4Address = true
		}

View on GitHub (pinned to cfe32b8be6)

Solutions

1. Run the proxy with CAP_NET_ADMIN or privileged
2. Install/verify iptables and nftables in the image and their modules on the host
3. Pin TS_DEBUG_FIREWALL_MODE to the stack the host actually supports
4. Read the wrapped error for the failing backend command and remediate that

if err := nfr.AddDNATRule(dst, local); err != nil {
    var ee *exec.ExitError
    if errors.As(err, &ee) {
        log.Printf("netfilter stderr: %s", ee.Stderr)
    }
    return fmt.Errorf("installing rule for forwarding traffic to tailnet IP: %w", err)
}

When it happens

Trigger: 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.

Common situations: Operator proxies deployed with restricted securityContext; distroless images without firewall tools; hosts with nftables-only kernels and an iptables-mode runner.

Related errors

• installing ingress proxy rules: %w
• error adding rules: %w
• error deleting rules: %w
• error ensuring rule: %w
• installing egress proxy rules: %w

AI-assisted analysis of tailscale/tailscale@cfe32b8be6 (2026-08-15). Data as JSON: /api/errors/a0178a784088a24b. Report an issue: GitHub.