container is waiting to start: kubectl logs has nothing to show because the container never started

Error from server (BadRequest): container … is waiting to start means there are no logs because there is no process. The reason the container has not started is in the pod's events, not in its logs.

Applies to: All Kubernetes versions

What it means

Logs come from a container's stdout and stderr, so a container that has never run has none, and the API server returns a BadRequest saying so. The message usually includes the waiting reason — ImagePullBackOff, CreateContainerConfigError, PodInitializing — which is the actual diagnosis. This matters because reaching for logs is the instinctive first move for any failing pod, and for this whole class of failure it is the wrong one: nothing has run yet, and every clue is in kubectl describe pod instead.

Most common causes

• The image cannot be pulled, so the container has never been created.
• A referenced ConfigMap or Secret is missing, blocking container configuration.
• Init containers are still running, so the app container has not started.
• A volume has not mounted.
• The pod is not yet scheduled onto a node.
• The container is in a back-off delay between restart attempts, having previously failed.

How to diagnose it

1. Read the waiting reason in the error message itself — it names the state.
2. Go to the events: kubectl describe pod POD, which explains why.
3. For a container in a restart back-off, ask for the previous container's logs instead: kubectl logs POD --previous.
4. For a multi-container pod, name the container you want: kubectl logs POD -c CONTAINER.
5. For init containers, name them explicitly — their logs are not returned by default.

How to fix it

1. Resolve the waiting reason. The logs become available as soon as the container runs.
2. Use --previous for a crash-looping container, since the current one has no output.
3. Use kubectl describe as the first command for any pod that is not running, rather than kubectl logs.
4. Watch for the container to start and stream from that point: kubectl logs -f POD begins once it does.

Notes

The habit worth forming is checking the pod's phase first. A Running pod's problems are in its logs; a Pending or Waiting pod's problems are in its events, and no amount of asking for logs will produce them.

Related

• ImagePullBackOff — Kubernetes could not pull the container image
• previous terminated container not found — There is no earlier container to read logs from

Sources

• Kubernetes documentation — kubectl logs
• Kubernetes documentation — Debug Pods
• Kubernetes documentation — Debug Running Pods