{"record":{"id":"cac61f858b515ef4","repo":"kubernetes/kubernetes","slug":"encountered-an-error-while-tearing-down-rules","errorCode":null,"errorMessage":"encountered an error while tearing down rules","messagePattern":"encountered an error while tearing down rules","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"cmd/kube-proxy/app/server_linux.go","lineNumber":328,"sourceCode":"// cleanupAndExit is true, it will attempt to remove rules from all known kube-proxy\n// modes. If it is false, it will only remove rules that are definitely not in use by the\n// currently-configured mode.\nfunc platformCleanup(ctx context.Context, mode kubeproxyconfig.ProxyMode, cleanupAndExit bool) error {\n\tvar encounteredError bool\n\n\t// Clean up iptables and ipvs rules if switching to nftables, or if cleanupAndExit\n\tif !isIPTablesBased(mode) || cleanupAndExit {\n\t\tencounteredError = iptables.CleanupLeftovers(ctx) || encounteredError\n\t\tencounteredError = ipvs.CleanupLeftovers(ctx) || encounteredError\n\t}\n\n\t// Clean up nftables rules when switching to iptables or ipvs, or if cleanupAndExit\n\tif isIPTablesBased(mode) || cleanupAndExit {\n\t\tencounteredError = nftables.CleanupLeftovers(ctx) || encounteredError\n\t}\n\n\tif encounteredError {\n\t\treturn errors.New(\"encountered an error while tearing down rules\")\n\t}\n\treturn nil\n}\n","sourceCodeStart":310,"sourceCodeEnd":332,"githubUrl":"https://github.com/kubernetes/kubernetes/blob/b882c60b4023bdf09264c2d5d30a2cadebc240fb/cmd/kube-proxy/app/server_linux.go#L310-L332","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before: iptables mode on image lacking iptables-nft, cleanup fails\n# after: run cleanup once, then restart with correct tooling\nkube-proxy --cleanup-and-exit --config=/var/lib/kube-proxy/config.conf\nkube-proxy --config=/var/lib/kube-proxy/config.conf","handlingStrategy":"try-catch","validationCode":"// preflight: verify the required netfilter tooling is present before cleanup\nfor _, bin := range []string{\"iptables\", \"ipset\"} {\n    if _, err := exec.LookPath(bin); err != nil {\n        return fmt.Errorf(\"missing required binary %q for kube-proxy cleanup\", bin)\n    }\n}","typeGuard":"// cleanupBackendsAvailable returns true when all backends for the mode have their binaries.\nfunc cleanupBackendsAvailable(mode string) bool {\n    switch mode {\n    case \"nftables\":\n        _, err := exec.LookPath(\"nft\")\n        return err == nil\n    default:\n        _, err := exec.LookPath(\"iptables\")\n        return err == nil\n    }\n}","tryCatchPattern":"// kube-proxy mode switch: cleanup is best-effort; log and proceed\nif err := platformCleanup(ctx, oldMode, false); err != nil {\n    klog.Warningf(\"cleanup encountered errors (mode=%s): %v; rules may need manual removal\", oldMode, err)\n}","preventionTips":["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."],"tags":["kubernetes","kube-proxy","iptables","ipvs","nftables","networking","cleanup"],"analyzedSha":"b882c60b4023bdf09264c2d5d30a2cadebc240fb","analyzedAt":"2026-08-07T04:07:48.144Z","schemaVersion":2},"datasetVersion":"2026-08-07T07:17:06.508Z"}