Kubernetes Error Codes: Container Name Must Be Specified

Kubernetes Error Codes: Container Name Must Be Specified


One of the biggest challenges with Kubernetes configurations is that they can be hard to express and debug at times. The relationship between Kubernetes constraints is defined in the form of YAML manifest files, which can easily return an error with a small change in environment variables. To overcome these misconfiguration problems or whenever a resource fails to execute, Kubernetes terminates them with error codes that contain the reason for failure.

Rather than seeing error codes as a problem, though, try to see them as an opportunity. Understanding these error codes can help you debug your Kubernetes application more quickly and more precisely. Having knowledge about error codes will help you achieve a deeper understanding of Kubernetes so that you’re less likely to commit such errors in the future.

There are many error code outputs from the Kubernetes command line (kubectl) that cluster admins can use to better understand the underlying cause of a pod error and debug. The `container name must be specified` error code, for instance, typically pops up when the user is trying to access a container inside a pod without specifying its name.

This article will explain what causes the `container name must be specified` error code as well as offer ways to troubleshoot and resolve the error.

What Causes This Error Code?

The `container name must be specified` error in Kubernetes, which is related to the `kubectl logs` command, primarily relates to pods with multiple containers. When a pod has more than one container and the user does not name a specific container when attempting to retrieve its related logs or data, the user will get the following error code:

Error : a container name must be specified for pod >POD_NAME<, choose one of:

How Is This Error Code Useful?

The `container name must be specified` Kubernetes error code precisely highlights two key points:

* The pod on which the user is trying to run kubectl commands is a multi-container pod.

* The containers that are connected to a multi-container pod are specified in the error code.

The Error Code in Action

To see what prompts this error code to output, follow along with this example.

Before you begin, you’ll need a working Kubernetes cluster with the kubectl command line tool properly configured in order to reproduce the `container name must be specified` error code. You should set up this example on a cluster running locally. If you don’t already have a local cluster running, create one by using minikube or through other Kubernetes installations.

Once you have the Kubernetes cluster running, you need to define a YAML file that contains a pod with multiple containers.

1. The YAML file defined below will deploy the first container, named container-one, based on the NGINX image and the second container, named container-two, based on the Ubuntu image. The second container writes the text “Hello, I am a multi-container pod” to the `index.html` file served by container-one.

apiVersion: v1
kind: Pod
  name: multicon-pod

  restartPolicy: Never

  - name: shared-data
    emptyDir: {}


  - name: container-one
    image: nginx
    - name: shared-data
      mountPath: /usr/share/nginx/html

  - name: container-two
    image: ubuntu
    - name: shared-data
      mountPath: /pod-data
    command: ["/bin/sh"]
    args: ["-c", "echo Hello, I am a multi-container pod > /pod-data/index.html"]

2. Save the changes as a YAML file (in this case, `multicon-pod.yaml`) and then deploy this multi-container pod by using the following command:

kubectl apply -f multicon-pod.yaml


pod/multicon-pod created


3. After deploying the pod, the containers will take a little bit of time to change to the running state. For this example, don’t worry about the functionality of the multi-container pod; the point is to reproduce the error code.

Check whether kubectl is able to retrieve the created pod:

kubectl get pods


multicon-pod   1/2     NotReady   0          119s

The pod is available but it isn’t yet running completely (one of the containers is ready). That’s not what you’re concerned about, though.

4. Try to get logs of the multi-container pod using the following command:

kubectl logs multicon-pod


error: a container name must be specified for pod multicon-pod, choose one of: [container-one container-two]

The response will output the `container name must be specified` error code.

How Do You Resolve This Error Code?

To resolve the `container name must be specified` error code, you must provide a container name if the pod has more than one container.

To view the logs for a particular container in a pod, here is the typical command

kubectl logs >podname< -c >container_name<

Or you can see the logs from all containers using this code:

kubectl logs >podname< --all-containers

Try to use the first command with the pod deployed above:

kubectl logs multi-pod -c container-one


/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
2022/01/27 17:39:06 [notice] 1#1: using the "epoll" event method
2022/01/27 17:39:06 [notice] 1#1: nginx/1.21.6
2022/01/27 17:39:06 [notice] 1#1: built by gcc 10.2.1 20210110 (Debian 10.2.1-6) 
2022/01/27 17:39:06 [notice] 1#1: OS: Linux 5.11.0-36-generic
2022/01/27 17:39:06 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2022/01/27 17:39:06 [notice] 1#1: start worker processes
2022/01/27 17:39:06 [notice] 1#1: start worker process 31
2022/01/27 17:39:06 [notice] 1#1: start worker process 32
2022/01/27 17:39:06 [notice] 1#1: start worker process 33
2022/01/27 17:39:06 [notice] 1#1: start worker process 34
2022/01/27 17:39:06 [notice] 1#1: start worker process 35
2022/01/27 17:39:06 [notice] 1#1: start worker process 36

As you can see from the response, you can resolve the error code by specifying the container name with the multi-container pod.


You should now be familiar with the possible reasons why Kubernetes would return a `container name must be specified` error code. Keeping the above example in mind, you should also be able to easily troubleshoot this error by using a couple of kubectl commands.

Kubernetes error codes can be frustrating, but they can also tell you valuable information about your application and your infrastructure. When used properly, they are important tools to help you improve your software.

Learn from Nana, AWS Hero & CNCF Ambassador, how to enforce K8s best practices with Datree

Watch Now

🍿 Techworld with Nana: How to enforce Kubernetes best practices and prevent misconfigurations from reaching production. Watch now.

Reveal misconfigurations within minutes

3 Quick Steps to Get Started