The Ops Community ⚙️

Cover image for Troubleshooting "RunContainerError" for Kubernetes
Patrick Londa for Blink Ops

Posted on • Originally published at blinkops.com

Troubleshooting "RunContainerError" for Kubernetes

So you're using Kubernetes to manage your containerized services, but you have run into a snag. Your project isn't loading, and you're receiving a message which reads "RunContainerError".

Fortunately, Kubernetes has very helpful debugging tools that can readily streamline the troubleshooting process. Here's a step-by-step guide to troubleshooting the "RunContainerError" message for Kubernetes Pods and getting your project up and running.

What Does “RunContainerError” Mean?

The RunContainerError message will appear if the container is unable to start. When you receive the "RunContainerError" message, the application within the container hasn't even attempted to load, since the container itself has failed.

What Causes a Pod To Be In the “RunContainerError” State?

You will encounter the "RunContainerError" message if you attempt to mount a volume (usually ConfigMap or Secrets) that doesn't exist, or if you attempt to mount a read-only volume as read-write.

How to Troubleshoot Pods In the “RunContainerError” State

Here are all the steps you ought to take to manually troubleshoot Pods in the "RunContainerError" state:

1. Print Pod Details
First, use this command:

kubectl describe Pod <pod-name>
Enter fullscreen mode Exit fullscreen mode

This will print all the details of your Pod. Under the Events section, you'll see:

  • FirstSeen
  • LastSeen
  • Count
  • From
  • SubObjectPath
  • Type
  • Reason
  • Message

Check the Message section of the last event on the list. You should see the name of the volume that is causing your issue, as well as its type.

2. Check for Typos
First, look closely at the name of the problematic volume in the Message section. Is it exactly the same as the name of the volume you intend to point to? If not, update your Pod to include the proper name.

3. Check if the volume exists
If you have typed the name of the volume correctly, then the volume either doesn’t exist or there is an issue with permissions.

A volume might not exist if you didn’t create it yet, or if it failed to create. In the case that it failed to create, you can see this issue in the event log.

To create a new volume, please see this guide from Kubernetes. There are several dozen types of volumes, and the creation of each type of volume has its own process which must be followed. You can also reassign the pod to an existing volume.

4. Check the volume permissions
If the volume exists and you are referencing it accurately, then you probably have a permissions issue. For example, if you've attempted to load a read-only volume as read-write, you'll need to either create a new read-write volume, reassign the pod to an existing read-write volume, or change readOnly to true in the volumeMounts section of the Pod configuration file.

Top comments (0)