Docker Layers - failed to register layer: max depth exceeded

Version:

All docker versions

Error:

When attempting to launch a workspace you are presented with this error: “failed to register layer: max depth exceeded” in the logs. The error is also visible on the describe of a new pod (Under Events)

Warning Failed 12m (x7 over 26m) kubelet Failed to pull image "100.97.188.95:5000/dominodatalab/environment:63a051030e277d167bec6bfd-35": rpc error: code = Unknown desc = failed to register layer: max depth exceeded

Cause:

Docker images consist of stacked layers. Each instruction in a Dockerfile creates one new layer. When using the overlay2 storage driver, Docker enforces a maximum of 127 layers per image. This error occurs when your image exceeds that limit. Note that the base image your compute environment builds on may already use many layers. Your own Dockerfile instructions stack on top of those existing layers.

Resolution:

Reduce the total number of layers in your Dockerfile. The most effective approaches are combining multiple RUN instructions and using multi-stage builds.

1. Combine RUN instructions

Each separate RUN instruction creates a new layer. Combine related commands into a single RUN instruction using &&. Install all packages in one step:

RUN apt-get update && \
    apt-get install -y package1 && \
    apt-get install -y package2 && \
    apt-get install -y package3 && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

2. Use multi-stage builds

If your build process requires multiple tools, use multi-stage builds. Build artifacts in one stage, then copy only what you need into the final image. This avoids carrying intermediate layers into the final image:

FROM builder AS build
# Build commands go here

FROM base_image
# Copy artifacts from the build stage
COPY --from=build /path/to/artifacts /app

3. Create a new compute environment

If your layer count still exceeds 127 after combining instructions, the base image itself may account for too many layers. In that case, create a new compute environment in Domino and copy your existing Dockerfile instructions into it, confirming the total layer count stays within the 127-layer limit. For help editing Dockerfile instructions in a Domino compute environment, see Use Dockerfile instructions.

Additional resources

Dockerfile best practices — guidance on reducing layers and optimizing image size
Dockerfile reference — full reference for all Dockerfile instructions

​Version:

​Error:

​Cause:

​Resolution:

​1. Combine RUN instructions

​2. Use multi-stage builds

​3. Create a new compute environment

​Additional resources