Docker Build & Image Errors
Everything that breaks a `docker build` or an image pull/push: BuildKit "failed to solve", cache-key misses, layer and registry errors, pull-access-denied and Docker Hub rate limits, manifest-unknown and platform mismatches. Each guide opens with the cause and the exact `docker build`, `docker buildx`, and registry commands. Pick your error below, or paste the build output into the assistant.
Fix your error now
Paste the error or logs and let the Incident Assistant diagnose it, or run a guided triage prompt with AI — no copy-paste.
Every guide in this cluster
49 guides-
'failed to solve with frontend dockerfile.v0' BuildKit Build Failures
Fix 'failed to solve with frontend dockerfile.v0' in Docker BuildKit: resolve Dockerfile syntax errors, missing files, unresolved ARGs, base images, and cache key failures.
-
'pull access denied for <image>, repository does not exist or may require docker login' Registry Auth Failures
Fix Docker 'pull access denied... requested access to the resource is denied': run docker login, correct the namespace, check ~/.docker/config.json, and verify the image exists.
-
'toomanyrequests' Docker Hub Pull Rate Limit Failures
Fix Docker 'toomanyrequests' rate limit: authenticate pulls, use a pull-through mirror, pin digests, and stop anonymous Docker Hub throttling in CI.
-
'failed to compute cache key: not found' — Fix Missing COPY/ADD Source Paths
Fix 'failed to compute cache key: path not found' in Docker: resolve COPY/ADD sources missing from the build context, .dockerignore exclusions, and wrong paths.
-
'net/http: TLS handshake timeout' in Docker: Causes & Fix
Fix Docker's 'net/http: TLS handshake timeout' on registry pulls: usually a broken dockerd proxy or wrong docker0 MTU. Diagnose and unblock with real commands.
-
'ApplyLayer lchown operation not permitted' Image Extract Failure
Fix Docker 'failed to register layer: ApplyLayer ... lchown ... operation not permitted' errors: resolve rootless/userns UID mapping, restrictive filesystem, and storage-driver problems.
-
'blob upload unknown' — Fix Failed Image Pushes
Fix Docker 'blob upload unknown' on push: resolve interrupted chunked uploads, load balancer session affinity, proxy body limits, and registry storage issues so docker push completes.
-
'cannot create directory: Permission denied' — Volume & Bind-Mount Ownership
Fix Docker's 'cannot create directory: Permission denied' on volumes and bind mounts caused by UID/GID mismatches between the container user and host directory ownership.
-
'cannot stop container: permission denied' — Fix Daemon and Cgroup Signal Failures
Fix Docker 'cannot stop container permission denied': diagnose docker socket access, rootless and SELinux/AppArmor policies, stuck cgroups, and kill signals the runtime cannot deliver.
-
'conflict: unable to remove repository reference' Image Removal Failures
Fix Docker 'conflict: unable to remove image': clear containers using the image, handle multiple tags and child images, and force-remove references safely.
-
'context canceled' Build and Pull Cancellation Failures
Fix Docker 'context canceled': diagnose timeouts, interrupted builds, daemon restarts, and dropped connections that abort BuildKit and pull operations.
-
'COPY failed: file not found in build context' Build Context Errors
Fix 'COPY failed: file not found in build context' in Docker: correct context-relative paths, .dockerignore exclusions, wrong build context, case sensitivity, and COPY --from.
-
'denied: requested access to the resource is denied' — Fix docker push Auth
Fix Docker push 'denied: requested access to the resource is denied': log in to the right registry, tag with the correct namespace, and grant push scope for your repository.
-
unknown instruction' — Fix Invalid Dockerfile Syntax
Fix 'Dockerfile parse error line n: unknown instruction' in Docker: catch typos, stray text, wrong casing, missing line continuations, and non-Dockerfile content.
-
'error getting credentials - err: exit status 1' — Fix Credential Helpers
Fix Docker 'error getting credentials err exit status 1 out': repair a broken credsStore helper, install docker-credential binaries, and clear corrupt entries in config.json.
-
'error pulling image configuration: download failed' — Fix Pulls
Fix Docker 'error pulling image configuration: download failed': repair blocked config-blob downloads from proxies, TLS interception, DNS, rate limits, and CDN issues so image pulls complete.
-
'failed to export image' buildx Export and Push Failure
Fix Docker buildx 'failed to solve: failed to export image' errors: diagnose registry auth, cache export, --output, and --push problems and get builds exporting cleanly.
-
'failed to read dockerfile: no such file or directory' — Fix Missing Dockerfile Path
Fix 'failed to read dockerfile: open /Dockerfile: no such file or directory' in Docker: point -f at the right file, fix the build context, and check casing.
-
'failed to register layer' Storage and Layer Extraction Failures
Fix Docker 'failed to register layer': free disk space and inodes, prune overlay2, repair userns-remap chown errors, and re-pull corrupted layers. Diagnose with system df.
-
'failed to solve: rpc error code = Unknown' BuildKit Failure
Fix Docker BuildKit 'failed to solve: rpc error: code = Unknown desc' build failures: diagnose the frontend/gRPC error, read the real cause, and rebuild cleanly with buildx.
-
'Forbidden path outside the build context' — COPY/ADD Beyond the Context
Fix 'Forbidden path outside the build context' in Docker: keep COPY/ADD sources inside the context root, restructure it, or use multi-stage builds.
-
'http: server gave HTTP response to HTTPS client' Registry Pull/Push Failure
Fix Docker's 'http: server gave HTTP response to HTTPS client' error when pulling or pushing to a private registry: configure insecure-registries in daemon.json and restart Docker.
-
'image does not match the specified platform' — Pull the Right Architecture
Fix Docker 'image does not match the specified platform: wanted linux/amd64, actual linux/arm64' by pulling with --platform, using a multi-arch manifest, or building for the target arch.
-
'image is being used by running container' — Cannot Delete Image
Fix 'conflict: unable to delete image - image is being used by running container': stop and remove the dependent containers first, then remove the image or re-tag safely.
-
'image operating system "linux" cannot be used on this platform' — OS/Arch Mismatch
Fix Docker's 'image operating system "linux" cannot be used on this platform' error caused by OS or CPU architecture mismatches between an image and your host.
-
'invalid reference format' — Malformed Image Name or Tag
Fix 'invalid reference format' in Docker: correct malformed image names, uppercase repos, bad tags, stray spaces, and misquoted run arguments.
-
'layers from manifest don't match image configuration' Pull Validation Failures
Fix Docker 'layers from manifest don't match image configuration': clear corrupted pull caches, registry mirror mismatches, and broken multi-arch manifests.
-
'lookup <registry> on 127.0.0.11:53: no such host' — Fix Docker DNS
Resolve Docker's 'no such host' registry error: understand the 127.0.0.11 embedded DNS resolver, fix registry typos, configure daemon.json dns settings, and handle corporate DNS.
-
'manifest unknown' Missing Tag or Digest
Fix Docker 'manifest for <image>:<tag> not found: manifest unknown': use a tag that exists, push the missing tag, check digests, and inspect the registry with manifest inspect.
-
'Mounts denied: The path is not shared from the host' — Desktop File Sharing
Fix Docker Desktop's 'Mounts denied: The path is not shared from the host and is not known to Docker' error by configuring file sharing for bind-mounted paths.
-
'name unknown: repository name not known to registry' — Wrong Repo Path
Fix Docker's 'name unknown: repository name not known to registry' error caused by wrong repository paths, missing namespaces, or repos that were never created.
-
'newuidmap: write to uid_map failed' Rootless Setup
Fix rootless Docker's 'newuidmap: write to uid_map failed: Operation not permitted' error: repair /etc/subuid, /etc/subgid, and the setuid bit on newuidmap/newgidmap.
-
'no basic auth credentials' — Fix Registry Push/Pull Auth
Fix 'no basic auth credentials' in Docker: log in to the right registry, match the image name to your login host, refresh expired tokens, and repair the credential store.
-
'no builder instance found' docker buildx Failure
Fix Docker's 'ERROR: no builder instance found' from docker buildx: create and select a builder with docker buildx create --use and confirm the driver is running.
-
'no matching manifest for linux/amd64 in the manifest list entries' Platform Mismatch
Fix Docker 'no matching manifest for linux/amd64': pull with --platform, build multi-arch images with buildx, inspect available platforms, and enable qemu emulation.
-
'No such image' — Fix Missing Image References and Tags
Fix 'Error response from daemon: No such image' in Docker: pull the image, match the exact tag, check the registry and local image list, and fix build tags.
-
'OCI runtime exec failed: permission denied' — Fix Non-Executable Entrypoints
Fix Docker 'OCI runtime exec failed permission denied': set the executable bit on entrypoints, handle CRLF and missing interpreters, and resolve noexec mounts and security policies.
-
'permission denied while trying to connect to the Docker daemon socket' Access Errors
Fix 'Got permission denied' on /var/run/docker.sock by adding your user to the docker group, re-logging in, or switching to rootless Docker safely.
-
'pull access denied, repository does not exist or may require docker login'
Fix Docker 'pull access denied, repository does not exist or may require docker login': correct the image name and registry, log in for private repos, and verify the tag exists.
-
'received unexpected HTTP status: 500 Internal Server Error' — Registry Failures
Fix Docker's 'received unexpected HTTP status: 500 Internal Server Error' during push or pull, caused by registry backend, storage, or proxy failures upstream.
-
'requested image's platform does not match host' — Run Native or Emulate
Fix Docker's platform mismatch warning: understand QEMU emulation slowdowns, pin --platform, build multi-arch images with buildx, and pick base images that match your host.
-
'target stage could not be found' — Fix Multi-Stage Build Target Names
Fix 'failed to solve: target stage could not be found' in Docker: match --target and COPY --from names to your Dockerfile's 'AS' stage names and check typos.
-
'the buildx builder container is not running' BuildKit Failure
Fix Docker Buildx's 'buildkit ... the buildx builder container is not running' error: diagnose stopped builder containers, restart the builder, or recreate the buildx instance.
-
'the Dockerfile (Dockerfile) cannot be empty' — Fix Blank or Truncated Dockerfiles
Fix 'the Dockerfile (Dockerfile) cannot be empty' in Docker: restore truncated files, fix zero-byte writes, comment-only files, and wrong -f targets.
-
'unable to prepare context: path not found' — Fix Invalid Build Context Paths
Fix 'unable to prepare context: path not found' in Docker: point the build context at an existing directory, fix argument order, and check relative paths.
-
'unauthorized: authentication required' — Fix Docker Login and Tokens
Fix Docker 'unauthorized: authentication required': log in to the right registry, refresh expired tokens, handle rate limits, and configure non-interactive CI credentials correctly.
-
'unauthorized: authentication required' Registry Token Failure
Fix Docker 'unauthorized: authentication required' errors pulling or pushing to a private registry: re-authenticate, fix token scope and endpoint, and repair credential-helper config.
-
'unexpected EOF' on Image Pull — Fix Broken Layer Downloads
Fix Docker 'unexpected EOF' during pull: repair truncated layer downloads from network drops, proxy/MTU issues, registry timeouts, and corrupt cache, then pull large images reliably.
-
'x509: certificate signed by unknown authority' Registry TLS Failures
Fix Docker's x509 certificate signed by unknown authority error: install the registry CA in /etc/docker/certs.d, update the trust store, and restart dockerd.
Docker with AI AI prompts
Copy-paste, production-safe prompts for this stack.
Docker with AI command center
Top errors, validators, and runbooks for the whole stack.
Frequently asked questions
What does "failed to solve with frontend dockerfile.v0" mean?
--progress=plain for the full log. See failed to solve.How do I fix Docker Hub "toomanyrequests" rate limits?
docker login (authenticated limits are higher), pull through a mirror/registry cache, or move base images to a private registry. See Docker Hub rate limit.