Start Building for Free

Debugging Container ID Cannot Be Mapped to Host ID Error

5 days ago1 min read
Server v4.x
Server v3.x
Server v2.x
On This Page
  • Background
  • Problem
  • Solution
  • See Also

When starting a container, you may see this error message:

failed to register layer: Error processing tar file (exit status 1): container id 1000000 cannot be mapped to a host id

This document explains the problem and how to fix it.


The user namespace (userns) is a feature of the Linux kernel that adds another security layer to Linux containers. The userns allows a host machine to run containers outside its UID/GID namespace. This means all containers can have a root account (UID 0) in their own namespace and run processes without receiving root privileges from the host machine.

When a userns is created, the Linux kernel provides a mapping between the container and the host machine. For example, if you start a container and run a process with UID 0 inside of it, the Linux kernel maps the container’s UID 0 to a non-privileged UID on the host machine. This allows the container to run a process as if it were the root user, while actually being run by the non-root user on the host machine.


The error is caused by a userns remapping failure. CircleCI runs Docker containers with userns enabled in order to securely run customers’ containers. The host machine is configured with a valid UID/GID for remapping. This UID/GID must be in the range of 0 - 65535.

When Docker starts a container, Docker pulls an image and extracts layers from that image. If a layer contains files with UID/GID outside of the accepted range, Docker cannot successfully remap and fails to start the container.


To fix this error, you must update the files’ UID/GID and re-create the image.

If you are not the image maintainer, congratulations: it’s not your responsibility. Contact the image maintainer and report the error.

If you are the image maintainer, identify the file with the high UID/GID and correct it. First, grab the high UID/GID from the error message. In the example presented at the top of this document, this value is 1000000. Next, start the container and look for the files which receive that invalid value.

Below is an example of finding an invalid file inside circleci/doc-highid using the find command:

# Start a shell inside the container
$ docker run -it circleci/doc-highid sh

# Find the file with high UID/GID
$ find / \( -uid 1000000 \)  -ls 2>/dev/null
     50      0 -rw-r--r--   1 veryhigh veryhigh        0 Jul  9 03:05 /file-with-high-id

# Confirm that the file has high UID/GID
$ ls -ln file-with-high-id
-rw-r--r-- 1 1000000 1000000 0 Jul  9 03:05 file-with-high-id

After locating the offending file, change its ownership and re-create the image.

Note: It is possible for an invalid file to be generated and removed while a container is building. In this case, you may have to modify the RUN step in the Dockerfile itself. Adding && chown -R root:root /root to the problem step should fix the problem without creating a bad interim.

See Also

Refer to the following Microsoft forum post for additional links if you get more errors after performing this procedure.

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.