Skip to content
DevOps AI ToolKit
Newsletter
All prompts
AI for Kubernetes & Helm Difficulty: Beginner ClaudeChatGPTCursor

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

More Kubernetes & Helm prompts & error guides

Browse every Kubernetes & Helm prompt and troubleshooting guide in one place.

Free download · 368-page PDF

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.