Troubleshooting

Organised by what you observe, not by what the cause turns out to be.

Scaffold status

Platform-specific failure modes are added here as they are confirmed. The general Kubernetes diagnosis below applies today.

Start here

Three commands identify the cause of most problems:

oc get events -n <project> --sort-by=.lastTimestamp | tail -20
oc describe pod <pod> -n <project>
oc logs <pod> -n <project> --previous

--previous reads the logs of the instance that crashed, which is usually the one that knows why.

Pod will not start

Status	Usual cause	Check
Pending	Nothing can schedule it — quota, resources or node selector	oc describe pod events, oc describe quota -n <project>
ImagePullBackOff	Wrong image name, or missing registry credentials	Image reference, and the pull Secret on the service account
CrashLoopBackOff	The container starts and exits	oc logs --previous
CreateContainerConfigError	A referenced Secret or ConfigMap does not exist	oc get secret,configmap -n <project>

Pod runs but is killed

OOMKilled in the pod status means the container exceeded its memory limit. Either the limit is too low or the workload leaks:

oc describe pod <pod> -n <project> | grep -A3 "Last State"
oc adm top pod -n <project>

Cannot reach a service

Work outward, one hop at a time:

# 1. Does the Service have endpoints? (empty = no ready pods match the selector)
oc get endpoints <service> -n <project>

# 2. Can another pod in the namespace reach it?
oc run tmp --rm -it --image=nicolaka/netshoot -n <project> -- curl -sS <service>:<port>

# 3. Is a NetworkPolicy blocking it?
oc get networkpolicy -n <project>

Default-deny egress blocks same-namespace traffic too

If you applied a default-deny-egress policy with podSelector: {}, your own pods cannot talk to each other either — including DNS. Add a self-referencing egress rule and a DNS allowance. See Networking.

Volume will not attach

oc get pvc -n <project>              # Pending = not provisioned yet
oc describe pvc <pvc> -n <project>   # events explain why

A ReadWriteOnce volume can only be attached to one node at a time. A second pod scheduled elsewhere will wait indefinitely — that is the access mode working as designed, not a fault. Use ReadWriteMany if you need shared access.

Still stuck

Collect this before you ask for help — it answers the first three questions anyone will have:

oc get all -n <project>
oc get events -n <project> --sort-by=.lastTimestamp
oc describe pod <pod> -n <project>

Then contact support through the console.