Docs

Volcengine Kubernetes Engine

Pod exception troubleshooting

How do I fix a pod that remains in the ImagePullBackOff state?

Issue description

The pod remains in the ImagePullBackOff state for an extended period.

Cause analysis

If the pod is in the ImagePullBackOff state, the pod has been successfully scheduled, but container image pulling failed. Possible reasons are as follows:

Incorrect image address

No imagePullSecret configured for the private image

Invalid domain configuration for the private image

Corrupted image file

Image pull timeout

Solution

Incorrect image address

Check whether the image address, name, and version are correctly configured. When the version tag is latest, confirm that an image with version tag latest exists in the image repository.

Run the following command to manually pull the image and confirm whether the image address is correct.

docker pull <imange-name>

No imagePullSecret configured for the private image

The pod pulls a private image. However, if no imagePullSecret is configured, or the configured Secret does not exist or is incorrect, authentication will fail, causing the pod to remain in the ImagePullBackOff state. The 401 Unauthorized event is recorded for the pod.

Solution: Configure an imagePullSecret to enable password-free image pulling for containers in the cluster. For details, see Using a VKE add-on for password-free image pulling over the internal network.

Invalid domain configuration for the private image

The pod uses a private image and imagePullSecrets are configured, but the domain name in these imagePullSecrets is inconsistent with the domain name for the workload. This will cause the pod to remain in the ImagePullBackOff state.

Solution: see How do I handle image pulling failures?

Corrupted image file

If the image file is corrupted, it cannot be used normally even after it is downloaded. In this case, you need to push the image file again.

Image pull timeout

When a large number of pods are started simultaneously on a node, image downloads may be queued. If there are many large-size images that require lengthy download times at the front of the queue, the pods positioned later in the queue will experience image pull timeouts. At this point, a pull QPS exceeded error is reported. An example of the error log is as follows.

The cause of this phenomenon is that the kubelet parameter serialize-image-pulls is configured for serial download, or the number of concurrent downloads exceeds the threshold.

tip

The pull QPS exceeded error does not impact the normal download of pod images. When a pod times out in the queue, it will rejoin the download queue and retry pulling the image.

Solution: To avoid Pod image pull timeouts and the pull QPS exceeded error, you can enable parallel downloads in kubelet and configure the number of concurrent downloads. For details, see Configuring kubelet parameters.

tip

For more detailed configuration instructions, see the kubelet documentation.

Last updated: 2026.07.23 14:31:46