kubectl port-forward Connection Failure Debug Prompt
Diagnose why kubectl port-forward drops, refuses, or hangs — pod not Ready, wrong target port, SPDY/websocket proxy issues, or an app bound to localhost inside the container — instead of guessing.
- Target user
- Developers and SREs debugging local cluster access
- Difficulty
- Beginner
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior SRE helping debug a failing `kubectl port-forward`. Reason from the specific error text and the pod/target state, not generic advice. I will provide some of: - The exact `kubectl port-forward` command and its full output/error - `kubectl get pod <name>` (READY, STATUS) and the container's `ports:` - The service definition if forwarding to a service - What the app binds to inside the container (0.0.0.0 vs 127.0.0.1) if known Classify the failure into one of these and prove it from the evidence: 1. **Pod not Ready** — port-forward only attaches to a running pod; if READY is 0/1 or STATUS is Pending/CrashLoopBackOff, that is the real problem, not the forward. 2. **Wrong target port** — the forward's remote port must match a port the container actually listens on; confirm against `containerPort` and, for a service, the `targetPort` mapping. 3. **App bound to localhost inside the container** — if the process listens on `127.0.0.1`, port-forward (which connects from the pod's network namespace) still works, but a common variant is the app binding to the wrong interface; explain how to tell. 4. **Connection reset / "lost connection to pod"** — tie this to the pod restarting, an idle timeout, or an intermediate proxy dropping the SPDY stream; recommend `--address` and retry behavior. 5. **RBAC / proxy errors** — `error upgrading connection` or 403 means the user lacks `pods/portforward` create permission or an API proxy blocks the upgrade; give the exact RBAC check. Output: (a) which class this is, (b) the evidence line, (c) the exact corrected command or fix, (d) a one-line verification (e.g. `curl localhost:<port>/healthz`). If evidence is missing, name the command to run.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Related prompts
-
Pod DNS ndots and Search Domain Latency Tuning Prompt
Cut DNS latency and failed lookups caused by the default ndots:5 and long search-domain lists — decide when to override dnsConfig, use FQDNs with a trailing dot, or keep cluster defaults.
-
metrics-server Unavailable and kubectl top Failure Debug Prompt
Fix 'metrics not available' / 'error: Metrics API not available' when kubectl top and HPAs stop working — diagnose the APIService, TLS/kubelet connectivity, and metrics-server flags instead of restarting blindly.
-
CrashLoopBackOff Triage From Describe and Logs Prompt
Walk a CrashLoopBackOff pod from kubectl describe, previous-container logs, and exit codes to a precise root cause and fix, instead of blindly restarting it.
-
Pending Pod Scheduling Diagnosis Prompt
Diagnose why a pod is stuck Pending by reading scheduler events, node capacity, and the pod's scheduling constraints, then propose the minimal change to get it scheduled.
More Kubernetes & Helm prompts & error guides
Browse every Kubernetes & Helm prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.