# Troubleshooting container builds (https://depot.dev/docs/container-builds/troubleshooting) This page provides an overview of common errors encountered when building container images with Depot, along with steps to resolve them. ## Error: `Keep alive ping failed to receive ACK within timeout` This error occurs when BuildKit is shut down due to runner resource starvation, often caused by an Out of Memory (OOM) condition. ### How to resolve To resolve this issue, try one of the following configuration changes: * **Scale up your worker size:** Increase the resources available to each build by selecting a larger worker size in your project settings. * **Enable auto-scaling:** Limit the number of builds running simultaneously on a given worker to prevent resource contention. For more information about auto-scaling, see the [Auto-scaling Guide](https://depot.dev/docs/container-builds/how-to-guides/autoscaling). If you continue to experience this error after adjusting your worker configuration, [reach out to support](/help) with your project ID and build details so we can help investigate resource usage patterns. ## Error: `Our services aren't available right now` When building images with Depot, you may see an error message similar to: ```text Error: failed to solve: failed to parse error response 400: Our services aren't available right now ``` This error typically occurs when trying to export build cache to GitHub Actions cache (`type=gha`) while using Depot builders. Depot builds automatically enable layer caching. You don't need to export cache to GitHub Actions cache, and attempting to do so can cause conflicts. ### How to resolve Remove both `--cache-from` and `--cache-to` from your build configuration: ```bash # Remove these flags: depot build \ --cache-from type=gha \ --cache-to type=gha \ . # Use this instead (Depot handles caching automatically): depot build . ``` Once removed, your builds will use Depot's native caching, which is faster and more reliable than GitHub Actions cache. If you continue seeing this error after removing the cache configurations, [reach out to support](/help) with your project ID and build details. ## Error: `client version 1.43 is too old` when using `--load` When running `depot build --load`, you may encounter an error like: ```text Error: failed to solve: failed to copy to tar: rpc error: code = Unknown desc = Error response from daemon: client version 1.43 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version ``` Docker Engine v29 raised its minimum supported API version to 1.44, but the Depot CLI may negotiate an older API version by default. This mismatch causes the Docker daemon to reject the image load request. ### How to resolve Use one of the following workarounds: * **Set `DOCKER_API_VERSION` environment variable** Force the CLI to negotiate a compatible API version: ```bash DOCKER_API_VERSION=1.52 depot build --load . ``` * **Lower the minimum API version in Docker Engine config** Add `{"min-api-version": "1.43"}` to your Docker Engine daemon configuration (for example `/etc/docker/daemon.json` on Linux, or via Docker Desktop’s **Docker Engine** settings), then restart the Docker daemon. ```json { "min-api-version": "1.43" } ``` * **Push to a registry and pull instead** Instead of loading the image directly, push it to a registry and pull it back: ```bash depot build --push -t your-registry/your-image:tag . docker pull your-registry/your-image:tag ``` If none of these workarounds resolve the issue, [reach out to support](/help) with your Docker Engine version and CLI version. ## Error: `failed to mount /tmp/buildkit-mount` If you see an error message like: ```text Error: failed to mount /tmp/buildkit-mountXXXXXXX: [{Type:overlay Source:overlay Target: Options:[lowerdir=/b/runc-stargz/snapshots/snapshotter/snapshots/XXXXX/fs ``` This indicates that BuildKit's snapshot manager cannot properly mount an overlay filesystem layer. This error commonly occurs when: * Cache layers become corrupted or inconsistent * Snapshot metadata is out of sync with the actual filesystem state * Previous builds left the cache in an inconsistent state * Storage backend issues affect the overlay filesystem ### How to resolve Reset your project's build cache to clear the corrupted layers: 1. Navigate to your [Depot Dashboard](https://depot.dev) 2. Go to your project settings 3. Locate the **Cache Management** section 4. Click **Reset Cache** or **Clear Build Cache** 5. Confirm the cache reset operation 6. Retry your container build After resetting the cache, your build should complete successfully. The first build after a cache reset may take slightly longer as the cache rebuilds. If the error persists after resetting the cache, [reach out to support](/help) with: * Your project ID * The full error message from your build logs * Whether this happens consistently or intermittently ## Error: `401 Unauthorized` during Docker pull If you encounter an error during container builds similar to: ```text Error: failed to solve: debian:trixie-slim: failed to resolve source metadata for http://docker.io/library/debian:trixie-slim: unexpected status from HEAD request to https://registry-1.docker.io/v2/library/debian/manifests/trixie-slim: 401 Unauthorized ``` This error typically indicates an issue with accessing Docker Hub. ### How to resolve This error can occur due to Docker Hub outages, rate limiting, or authentication issues. Try these solutions: **1. Check Docker Hub status** First, check if Docker Hub is experiencing an outage or service disruption by visiting: [Docker's official status page](https://status.docker.com/) If Docker Hub is experiencing issues, you can continue your workflow by temporarily switching to AWS's public Docker mirror (see option 2 below). **2. Switch to AWS Docker Mirror** 1. Identify the Docker image you need. For example, if you are using the Ubuntu image, the typical Docker Hub path would be `docker.io/library/ubuntu:latest`. 2. Replace the Docker Hub path with AWS's Docker mirror path. For Ubuntu, use: `public.ecr.aws/docker/library/ubuntu:latest`. 3. Update your Dockerfile or Docker commands to pull from the AWS mirror: ```dockerfile # Instead of: FROM ubuntu:latest # Use: FROM public.ecr.aws/docker/library/ubuntu:latest ``` Once Docker Hub is back online, you can switch back to the standard Docker Hub paths. **3. Authenticate with Docker Hub for higher rate limits** If you're hitting Docker Hub rate limits, you can authenticate with a Docker Hub account to increase your pull limits. Free Docker Hub accounts get higher limits than anonymous pulls, and paid accounts get even higher limits. To authenticate, create a Docker Hub account if you don't have one, then set up authentication in your build environment. ## Error: `failed to load ref` If you encounter a warning during container builds similar to: ```text ERROR: failed to load ref: 05e0j9uordhz0b72g9h3e32an: not found ``` This error indicates that BuildKit couldn't find a cached layer that it expected to exist. While this appears as an error in the logs, BuildKit typically recovers by rebuilding the missing layer, so your build should still complete successfully. ### How to resolve If you observe this warning frequently, increase the cache storage allocation: 1. Log in to your [Depot Dashboard](https://depot.dev). 2. Select the project and click **Settings**. 3. Increase one or both of **Cache Storage Policy** and **Cache Retention Policy** values. 4. Monitor your builds to verify if the fix worked. If you continue to see this warning after adjusting your cache settings, [reach out to support](/help) with your project ID and build details. ## Error: `.git directory not found in build context` When using Depot's `build-push-action` for Docker builds, you might encounter an error such as: ```text Error: "/.git/refs/heads": not found. Please check if the files exist in the context. ``` By default, BuildKit does not include the `.git` directory in the build context, and uses the `git://` protocol instead. This can cause issues if your build process needs access to git information (for example, to determine commit hashes or branch names). ### How to resolve Set the `BUILDKIT_CONTEXT_KEEP_GIT_DIR=1` build argument to tell BuildKit to keep the git repository in the context: ```yaml jobs: build: runs-on: ubuntu-latest permissions: contents: read id-token: write packages: write steps: - name: Check out uses: actions/checkout@v4 with: fetch-depth: 2 - name: Set up Depot CLI uses: depot/setup-action@v1 - name: Build and push container image uses: depot/build-push-action@v1 with: project: your_project_id push: true platforms: linux/arm64,linux/amd64 build-args: | COMMIT_HASH=${{ github.sha }} BUILDKIT_CONTEXT_KEEP_GIT_DIR=1 ``` For more information, refer to the [Docker documentation on keeping the git directory in the build context](https://docs.docker.com/build/building/context/#keep-git-directory). If you continue to see git-related errors after adding this build argument, verify that your checkout step is fetching the necessary git history and [reach out to support](/help) if needed. ## Error: `cannot merge resource due to conflicting Schema URL` When running `depot build` or `depot bake`, you may encounter an error message like: ```text Error: cannot merge resource due to conflicting Schema URL ``` This error is typically caused by conflicting OpenTelemetry (OTEL) environment variables set in your local build environment. These environment variables can interfere with Depot's internal telemetry system. ### How to resolve Set the environment variable `DEPOT_DISABLE_OTEL=1` in your environment before running `depot build`. This variable disables the embedded OpenTelemetry tracing in Depot CLI. Use this to prevent conflicts when your environment has existing OpenTelemetry instrumentation: ```bash export DEPOT_DISABLE_OTEL=1 depot build . ``` Alternatively, you can set it inline with your build command: ```bash DEPOT_DISABLE_OTEL=1 depot build . ``` If you're using a CI/CD environment, add `DEPOT_DISABLE_OTEL=1` to your environment variables for the build step. If the error persists after setting this environment variable, [reach out to support](/help) with your project ID and build details. ## Error: `remote error: tls: bad record MAC` When building container images, you may encounter an error like: ```text Error: failed to receive status: rpc error: code = Unavailable desc = error reading from server: remote error: tls: bad record MAC ``` This error indicates that the connection between Depot CLI and the Depot builder dropped during the build. BuildKit requires the client to remain connected throughout the build process. Once the Depot runner detects that BuildKit is running, our API establishes a connection with the host running Depot CLI. This connection must remain stable for the duration of the build. If the connection drops (even briefly), BuildKit interprets this as the client disconnecting and cancels the build. ### How to resolve This error is typically caused by network instability on the client side. Check for: * **VPN connections:** Virtual private networks can cause intermittent connection drops, especially when switching networks or during reconnection events * **Firewall rules:** Aggressive firewalls may terminate long-lived connections * **Wi-Fi instability:** Weak or congested wireless connections can cause packet loss * **Router issues:** Some routers have connection timeout settings that affect long-running connections * **ISP issues:** Internet service provider outages or routing problems can cause intermittent connectivity If you continue experiencing connection issues from your local machine, consider triggering builds from a CI platform instead. CI environments typically have more stable network connections and are better suited for running longer builds. See our [CI integration guides](/docs/container-builds/quickstart#continuous-integration) for setup instructions. ## Error: `timed out connecting to machine: failed to create temp file` When running a build with Depot CLI, you may encounter an error similar to: ```text Error: timed out connecting to machine: failed to create temp file: open /var/folders/zz/zyxvpxvq6csfxvn_n0000000000000/T/depot-cert4068571078: permission denied ``` This error indicates that Depot CLI is unable to write the TLS certificate file to a temporary directory on your local machine. The client-side TLS certificate is required to establish secure communication with the remote build server. ### How to resolve * Try restarting your terminal session * Check available disk space on your local machine * Verify your user has write permissions to the directory shown in the error message * If using an antivirus or other security software, check if it's blocking file operations on the temporary directory If the issue persists, [reach out to support](/help) with your OS version and any security software you're running. ## Build hangs or builder won't start If your build hangs or a builder isn't coming online to serve build requests, this may be caused by: * A deadlock in BuildKit * A builder that isn't coming online to serve the build request * Build cache is full and needs to be cleared If you see any of these issues, you can reset the build cache for a project. ### How to resolve Resetting the build cache purges the cache volume and launches a new build machine with a clean slate: 1. Go to the project's `Settings` page 2. Click the `Reset build cache` button at the bottom ## Multi-platform/multi-architecture image has a 3rd image with platform `unknown/unknown` Docker introduced a new [provenance feature](https://docs.docker.com/build/attestations/slsa-provenance/) that tracks some info about the build itself, and it's implemented by attaching the data to the final image "manifest list". Many registries like GitHub Container Registry display the provenance data as an `unknown/unknown` image architecture. ### How to resolve If you don't care about provenance or want a cleaner list in your registry, you can disable provenance during your image build: ```bash depot build --provenance false ``` **When using `depot/build-push-action` or `depot/bake-action`:** You can set `provenance` to `false` in your workflow step to disable provenance: ```yaml - uses: depot/build-push-action@v1 with: ... provenance: false ... ``` ## Cannot pull from private registry during build When building container images that need to pull from private registries (like in a `FROM` statement), you may need to provide authentication credentials to Depot. ### How to resolve The `depot` CLI automatically uses your local Docker credentials provider. Any registry you've logged into with `docker login` is available when running a Depot build. For example, if your Dockerfile references a private registry: ```dockerfile FROM my-private-registry/project/image:version ... ``` Ensure you're logged into the registry from the machine where you're running `depot build`: ```bash docker login my-private-registry depot build . ``` If you're still experiencing authentication issues: 1. Confirm you're logged into the registry on the machine running `depot build` 2. Test that you can pull the image directly: `docker pull my-private-registry/project/image:version` 3. If the pull succeeds but the build fails, [reach out to support](/help) with your project ID and build details ## For AI Agents The full site index is at [llms.txt](https://depot.dev/llms.txt). Append `.md` to any documentation, blog, changelog, or customer URL to fetch its markdown source directly.