What causes "encountered an error while tearing down rules" in kubernetes/kubernetes?

Check the kube-proxy logs immediately before this line for which CleanupLeftovers failed and why.

encountered an error while tearing down rules

Error message

encountered an error while tearing down rules

What it means

kube-proxy's Linux platformCleanup runs CleanupLeftovers for iptables/ipvs/nftables (depending on target mode and --cleanup-and-exit) and aggregates failures into encounteredError. If any cleanup routine reports failure, it returns this generic teardown error. It does not identify which backend failed — consult preceding logs from the CleanupLeftovers calls.

Source

Thrown at cmd/kube-proxy/app/server_linux.go:328

// cleanupAndExit is true, it will attempt to remove rules from all known kube-proxy
// modes. If it is false, it will only remove rules that are definitely not in use by the
// currently-configured mode.
func platformCleanup(ctx context.Context, mode kubeproxyconfig.ProxyMode, cleanupAndExit bool) error {
	var encounteredError bool

	// Clean up iptables and ipvs rules if switching to nftables, or if cleanupAndExit
	if !isIPTablesBased(mode) || cleanupAndExit {
		encounteredError = iptables.CleanupLeftovers(ctx) || encounteredError
		encounteredError = ipvs.CleanupLeftovers(ctx) || encounteredError
	}

	// Clean up nftables rules when switching to iptables or ipvs, or if cleanupAndExit
	if isIPTablesBased(mode) || cleanupAndExit {
		encounteredError = nftables.CleanupLeftovers(ctx) || encounteredError
	}

	if encounteredError {
		return errors.New("encountered an error while tearing down rules")
	}
	return nil
}

View on GitHub (pinned to b882c60b40)

Solutions

Check the kube-proxy logs immediately before this line for which CleanupLeftovers failed and why.
Ensure the required binaries exist and are in PATH (iptables/iptables-nft, ipset, ipvsadm) and the pod is privileged / has NET_ADMIN.
Run kube-proxy --cleanup-and-exit once to reset, then restart in the desired mode.
For nftables mode use an image with nft; for ipvs ensure kernel modules (ip_vs*) are loaded.
Switch proxy mode to one whose tooling is present (e.g. iptables vs nftables) if the target backend is unavailable.

Example fix

# before: iptables mode on image lacking iptables-nft, cleanup fails
# after: run cleanup once, then restart with correct tooling
kube-proxy --cleanup-and-exit --config=/var/lib/kube-proxy/config.conf
kube-proxy --config=/var/lib/kube-proxy/config.conf

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: verify the required netfilter tooling is present before cleanup
for _, bin := range []string{"iptables", "ipset"} {
    if _, err := exec.LookPath(bin); err != nil {
        return fmt.Errorf("missing required binary %q for kube-proxy cleanup", bin)
    }
}

Type guard

// cleanupBackendsAvailable returns true when all backends for the mode have their binaries.
func cleanupBackendsAvailable(mode string) bool {
    switch mode {
    case "nftables":
        _, err := exec.LookPath("nft")
        return err == nil
    default:
        _, err := exec.LookPath("iptables")
        return err == nil
    }
}

Try / catch

// kube-proxy mode switch: cleanup is best-effort; log and proceed
if err := platformCleanup(ctx, oldMode, false); err != nil {
    klog.Warningf("cleanup encountered errors (mode=%s): %v; rules may need manual removal", oldMode, err)
}

Prevention

Run kube-proxy privileged / with NET_ADMIN and an image containing iptables, ipset, nft as needed.
Run --cleanup-and-exit once when switching modes to reset state.
Capture logs around CleanupLeftovers to pinpoint the failing backend.
Load required kernel modules (ip_vs*, nf_tables) on the host.

When it happens

Trigger: platformCleanup on Linux where iptables.CleanupLeftovers, ipvs.CleanupLeftovers, or nftables.CleanupLeftovers returns true (error). Triggered on kube-proxy mode switch or --cleanup-and-exit. server_linux.go:313-329.

Common situations: Missing iptables/ipvs/nft binaries or insufficient CAP_NET_ADMIN (non-privileged pod); corrupted rules tables; partial previous run leaving inconsistent state; mode mismatch (e.g. leftover ipvs rules while running iptables); container image lacking the netfilter tooling.

Related errors

AI-assisted analysis of kubernetes/kubernetes@b882c60b40 (2026-08-07). Data as JSON: /api/errors/cac61f858b515ef4. Report an issue: GitHub.