Debugging Container ID Cannot Be Mapped to Host ID Error
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.
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.
userns is created,
the Linux kernel provides a mapping between the container and the host machine.
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
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
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
# 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.
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.
&& chown -R root:root /root to the problem step
should fix the problem without creating a bad interim.
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.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.