This page provides an overview of common errors encountered when building container images with Depot, along with steps to resolve them.
Keep alive ping failed to receive ACK within timeoutThis 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.
If you continue to experience this error after adjusting your worker configuration, reach out to support with your project ID and build details so we can help investigate resource usage patterns.
Unable to acquire machine, please retryIf you encounter a container build failure with the error message Unable to acquire machine, please retry, this indicates an issue with machine availability or BuildKit responsiveness. This error can occur for two main reasons:
1. Regional capacity or maintenance issues:
2. BuildKit resource exhaustion:
This is often the same underlying cause as the Keep alive ping failed to receive ACK within timeout error. When BuildKit is overwhelmed, existing builds may see keep-alive ping failures, while new builds attempting to connect see this unable to acquire machine error.
How to resolve
First, check status.depot.dev for any reported outages. If there's an active incident in a certain region, you can switch your project to a different region temporarily.
If there are no reported incidents, this is likely a resource exhaustion issue. Try one of these 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.
If you continue experiencing this error after checking for incidents and adjusting your worker configuration, reach out to support with:
Our services aren't available right nowWhen building images with Depot, you may see an error message similar to:
Error: failed to solve: failed to parse error response 400: Our services aren't available right nowThis 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:
# 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 with your project ID and build details.
failed to mount /tmp/buildkit-mountIf you see an error message like:
Error: failed to mount /tmp/buildkit-mountXXXXXXX: [{Type:overlay Source:overlay Target: Options:[lowerdir=/b/runc-stargz/snapshots/snapshotter/snapshots/XXXXX/fsThis indicates that BuildKit's snapshot manager cannot properly mount an overlay filesystem layer.
This error commonly occurs when:
How to resolve
Reset your project's build cache to clear the corrupted layers:
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 with:
401 Unauthorized during Docker pullIf you encounter an error during container builds similar to:
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 UnauthorizedThis 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
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
docker.io/library/ubuntu:latest.public.ecr.aws/docker/library/ubuntu:latest.# Instead of:
FROM ubuntu:latest
# Use:
FROM public.ecr.aws/docker/library/ubuntu:latestOnce 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.
.git directory not found in build contextWhen using Depot's build-push-action for Docker builds, you might encounter an error such as:
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:
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=1For more information, refer to the Docker documentation on keeping the git directory in the build context.
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 if needed.
Each project in Depot represents a cache namespace shared among all systems and users that build it. The cache allows certain steps in your Dockerfile to be skipped in subsequent runs if their associated layer hasn't changed since the last time it was built. There can be times when you want to purge this cache.
We optimize Depot so that these issues rarely happen. However, if you see any of these issues, you can reset the build cache for a project. Resetting the build cache purges the cache volume and launches a new build machine with a clean slate. You can reset the build cache for a project via these steps:
Settings pageReset build cache button at the bottomunknown/unknownDocker introduced a new provenance feature 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. If you don't care about provenance or want a cleaner list in your registry, you can disable provenance during your image build.
depot build --provenance falsedepot/build-push-action or depot/bake-actionYou can set provenance to false in your workflow step to disable provenance.
- uses: depot/build-push-action@v1
with:
...
provenance: false
...