Back to Blog

Troubleshooting Kubernetes Pods: The "RunContainerError"

If you receive the "RunContainerError" message when working with Kubernetes, here are the steps you should take to remedy your deployment.


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 Manually 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>

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.

Troubleshooting Made Simple with Blink:

You might have solved your problem quickly or ended up down a research rabbit hole. When you create a free Blink account, you can manage your Kubernetes troubleshooting in one place with the common error causes listed and your next steps just a click away.

Blink kubernetes troubleshooting automation

Create your free Blink account and troubleshoot your Kubernetes errors faster today.

Simplify your cloud operations

Sign up for Blink today

Transform your cloud operations today with a library of purpose-built DevOps and SecOps playbooks and hundreds of integrations.

Sign up