On this page
Troubleshoot common failures
Diagnose Pending, ImagePullBackOff, CrashLoopBackOff and unreachable Services with bounded checks.
For Enterprise Self-Hosted or a separately agreed technical evaluation. Not a Cloud customer procedure.
Before you start
You have a provided pilot cluster, a trusted kubeconfig, kubectl and access to an agreed namespace. Set KUBECONFIG, CP_CONTEXT and CP_NAMESPACE using the access guide before running the commands. The examples use a POSIX shell and a single access file. Grouped blocks stop at missing settings without closing your terminal; they do not provision infrastructure or grant permissions. Connect to your cluster →
Use the exact failed workload and container names. The examples target cloud-demo; replace names and selectors for your own application. Start with read-only checks and preserve evidence before changing or restarting resources.
1. Establish impact and location
Record what users cannot do, when the fault started, the last relevant change and whether all replicas or only one are affected. Reconfirm CP_CONTEXT and CP_NAMESPACE from handover before diagnosing.
(
: "${KUBECONFIG:?Set KUBECONFIG from your handover}"
: "${CP_CONTEXT:?Set CP_CONTEXT from your handover}"
: "${CP_NAMESPACE:?Set CP_NAMESPACE from your handover}"
case "$CP_CONTEXT:$CP_NAMESPACE" in
YOUR_*|*:YOUR_*) printf '%s\n' 'Replace the YOUR_ context and namespace placeholders first.' >&2; exit 1 ;;
esac
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" get deployment/cloud-demo
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" get pods -l app=cloud-demo
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" describe deployment cloud-demo
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" get events --field-selector type=Warning --sort-by=.metadata.creationTimestamp
)If API access itself fails, use the access guide first. An application restart does not fix an expired credential or an unreachable cluster API.
Connect to your cluster →2. Follow the Pod's evidence
(
: "${KUBECONFIG:?Set KUBECONFIG from your handover}"
: "${CP_CONTEXT:?Set CP_CONTEXT from your handover}"
: "${CP_NAMESPACE:?Set CP_NAMESPACE from your handover}"
case "$CP_CONTEXT:$CP_NAMESPACE" in
YOUR_*|*:YOUR_*) printf '%s\n' 'Replace the YOUR_ context and namespace placeholders first.' >&2; exit 1 ;;
esac
export CP_POD="YOUR_POD_NAME"
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" describe pod "$CP_POD"
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" logs "$CP_POD" -c app --since=15m --tail=100 --limit-bytes=32768
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" logs "$CP_POD" -c app --previous --tail=100 --limit-bytes=32768
)| Signal | Check next | Avoid |
|---|---|---|
| Pending / FailedScheduling | Events for insufficient resources, quota, taints/affinity or volume placement; check PVC state where applicable. | Increasing replicas or adding node-level permissions without a capacity review. |
| ImagePullBackOff / ErrImagePull | Image spelling/digest, registry reachability, image architecture and the approved pull credential reference. | Printing registry passwords or switching to an unreviewed public image. |
| CrashLoopBackOff | Previous logs, exit code, required configuration, writable paths and startup/probe behavior. | Disabling security/probes or restarting repeatedly before understanding the cause. |
| OOMKilled | Termination reason, memory limit and measured workload peaks; review for a leak or undersizing. | Removing all memory limits as the default fix. |
| Running, not Ready | Readiness/startup endpoint, port, configuration and dependencies; inspect probe failure events. | Treating Running as proof the application can receive traffic. |
Previous logs only exist when a prior container instance is available. A missing previous log is not proof of a successful prior run. Pod descriptions can include sensitive plain-text environment values; review them locally before sharing.
3. Trace an unreachable Service
(
: "${KUBECONFIG:?Set KUBECONFIG from your handover}"
: "${CP_CONTEXT:?Set CP_CONTEXT from your handover}"
: "${CP_NAMESPACE:?Set CP_NAMESPACE from your handover}"
case "$CP_CONTEXT:$CP_NAMESPACE" in
YOUR_*|*:YOUR_*) printf '%s\n' 'Replace the YOUR_ context and namespace placeholders first.' >&2; exit 1 ;;
esac
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" get service/cloud-demo -o wide
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" get pods -l app=cloud-demo --show-labels
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" get endpointslices -l kubernetes.io/service-name=cloud-demo
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" port-forward service/cloud-demo 8080:80 --address=127.0.0.1
)Check selector labels, target port and Ready backends. Test localhost while the port-forward is running, then stop with Ctrl+C. A successful local test narrows the problem but does not prove cluster DNS or public routing. For public failures, compare host/path, TLS and DNS against the agreed endpoint. For cluster-internal failures, ask for the network/DNS layer to be checked if you cannot inspect it within your role.
Domains, ingress & TLS → Use persistent storage →4. Escalate with a useful stopping point
Share the minimum redacted evidence. Do not delete namespaces, PVCs or finalizers to make a symptom disappear. Once resolved, record the cause, fix and prevention, then repeat the application acceptance test.
Get useful support quickly →Technical references
These Kubernetes references describe technical behavior. Your pilot agreement defines the capabilities confirmed for your cluster.
Use this guide within your agreed pilot scope. Kubernetes examples are not evidence of a generally available Cloud capability.