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.
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.
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.
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:
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.
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.
failed to load refIf you encounter a warning during container builds similar to:
ERROR: failed to load ref: 05e0j9uordhz0b72g9h3e32an: not foundThis 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.
If you observe this warning frequently, increase the cache storage allocation:
If you continue to see this warning after adjusting your cache settings, reach out to support with your project ID and build details.
.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).
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.
cannot merge resource due to conflicting Schema URLWhen running depot build or depot bake, you may encounter an error message like:
Error: cannot merge resource due to conflicting Schema URLThis 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.
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:
export DEPOT_DISABLE_OTEL=1
depot build .Alternatively, you can set it inline with your build command:
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 with your project ID and build details.
remote error: tls: bad record MACWhen building container images, you may encounter an error like:
Error: failed to receive status: rpc error: code = Unavailable desc = error reading from server: remote error: tls: bad record MACThis 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.
This error is typically caused by network instability on the client side. Check for:
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 for setup instructions.
timed out connecting to machine: failed to create temp fileWhen running a build with Depot CLI, you may encounter an error similar to:
Error: timed out connecting to machine: failed to create temp file: open /var/folders/zz/zyxvpxvq6csfxvn_n0000000000000/T/depot-cert4068571078: permission deniedThis 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.
If the issue persists, reach out to support with your OS version and any security software you're running.
If your build hangs or a builder isn't coming online to serve build requests, this may be caused by:
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:
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 falseWhen using depot/build-push-action or depot/bake-action:
You can set provenance to false in your workflow step to disable provenance:
- uses: depot/build-push-action@v1
with:
...
provenance: false
...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.
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:
FROM my-private-registry/project/image:version
...Ensure you're logged into the registry from the machine where you're running depot build:
docker login my-private-registry
depot build .If you're still experiencing authentication issues:
depot builddocker pull my-private-registry/project/image:version