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.

Patrick Londa
Feb 9, 2022
 min read
Share this post

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.

Blink Automation: Troubleshoot Pods with "RunContainerError" Message
Blink + Kubernetes
Try This Automation

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. With Blink, you can manage your Kubernetes troubleshooting in one place with the common error causes listed and your next steps just a click away.

Blink Automation: Troubleshoot a Kubernetes Pod
Blink Automation: Troubleshoot a Kubernetes Pod

This automation in the Blink library enables you to quickly get the details you need to troubleshoot a given Pod in a namespace.

When the automation runs, it does the following steps:

  1. Gets the Pod status.
  2. Gets the Pod details.
  3. Gets the container logs.
  4. Gets events related to the Pod.

With one automation, you skip the kubectl commands and get the information you need to correct the error.

Get started with Blink and troubleshoot Kubernetes errors faster today.

Automate your security operations everywhere.

Blink is secure, decentralized, and cloud-native. 
Get modern cloud and security operations today.

Get a Demo