> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domino.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Layers - failed to register layer: max depth exceeded

> Resolve the "failed to register layer: max depth exceeded" Docker error in Domino by reducing image layers via combined RUN commands or multi-stage builds.

## **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](https://docs.dominodatalab.com/en/latest/user_guide/813d89/use-dockerfile-instructions/).

## **Additional resources**

* [Dockerfile best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) — guidance on reducing layers and optimizing image size
* [Dockerfile reference](https://docs.docker.com/engine/reference/builder/) — full reference for all Dockerfile instructions


## Related topics

- [Troubleshooting](/knowledge-base/troubleshooting-overview.md)
- [Customize your Environment](/cloud/platform-capabilities/core-concepts/compute-environments/manage-compute-environments/5-edit-environment-definition.md)
- [Control plane security](/cloud/admin/security-and-compliance/control-plane-security.md)
- [Integrated deployment to CI/CD workflows](/cloud/platform-capabilities/features/models/integrate-ci-cd-workflows.md)