Docker

Build, run, compose, and registry errors - explained.

Debug Docker in CI: build failures, layer caching, disk exhaustion, registry auth and rate limits, BuildKit issues, and docker compose problems. Root causes and reliable fixes.

Image build

Dockerfile errors, BuildKit, and layer caching.

"the Dockerfile cannot be empty"Fix buildx "ERROR: failed to solve: the Dockerfile cannot be empty" in CI - BuildKit received a zero-byte or "refers to undefined secret"Fix Compose "service X refers to undefined secret Y" in CI - a service lists a secret that has no matching "attestations not supported"Fix Docker buildx "--provenance"/"--sbom" attestation failures in CI - attestations turn a build into a "buildx component missing"Fix Docker "BuildKit is enabled but the buildx component is missing or broken" in CI - `DOCKER_BUILDKIT=1` is "buildx bake" failedFix Docker "buildx bake" failures in CI - a bad HCL/JSON bake file, an undefined target or variable, or a "failed to receive status"Fix Docker "buildx failed with: ERROR: failed to build: failed to receive status: rpc error" in CI - the "invalid from flag value"Fix Docker "COPY --from=<x>: invalid from flag value" / stage not found in CI - a COPY --from referencing a "COPY failed: ... not found in build context"Fix the Docker "COPY failed: file not found in build context" error in CI, caused by copying a path absent "dockerfile parse error"Fix Docker "failed to solve: dockerfile parse error" in CI - unknown instructions, bad line continuations, or "failed to compute cache key ... not found"Fix the Docker "failed to compute cache key: ... not found" build error in CI, caused by a COPY or ADD source "file changed during build"Fix BuildKit "failed to compute checksum of ref" in CI - a file in the build context was modified or removed "failed to read dockerfile"Fix Docker "failed to solve: failed to read dockerfile" in CI - a missing Dockerfile, wrong -f path, or the "invalid file request"Fix Docker buildx "failed to solve: invalid file request <path>" in CI - a COPY/ADD or -f references a path "invalid mount config"Fix BuildKit "failed to solve: invalid mount config" in CI - a `RUN --mount=type=cache` declared a malformed "lstat /var/lib/docker"Fix BuildKit "failed to solve: lstat /var/lib/docker: permission denied" in CI - the builder tried to stat a "rpc error: code = Canceled"Fix Docker buildx "failed to solve: rpc error: code = Canceled" in CI - the build was cancelled because the "SSH agent not available"Fix BuildKit "failed to solve: ... SSH agent not available" / "no ssh forwarded" in CI - RUN --mount=type=ssh "target stage not found"Fix Docker "failed to solve: target stage X could not be found" in CI - a --target or COPY --from naming a "--mount requires BuildKit"Fix Docker "the --mount option requires BuildKit" in CI - RUN --mount cache/secret syntax used while the "too many open files"Fix Docker build "too many open files" / "EMFILE" during a RUN step in CI - the file-descriptor ulimit is too "failed to fetch oauth token"Fix BuildKit "failed to solve: failed to fetch oauth token: unexpected status: 401/403" in CI - the build "build must be a string or object"Fix Docker Compose "services.X.build must be a string or object" in CI - a malformed build key, usually a

Registry & pulls

Auth, rate limits, and manifest errors.

"imagetools create failed"Fix "docker buildx imagetools create" failing in CI - combining per-arch tags into one manifest list fails "denied: requested access"Fix Docker push "denied: requested access to the resource is denied" in CI - pushing to a repository your "HTTP response to HTTPS client"Fix Docker "http: server gave HTTP response to HTTPS client" in CI - pushing/pulling to a plain-HTTP registry "insecure-registries" not setFix Docker pulls/pushes failing because a registry needs an "insecure-registries" entry in CI - the daemon "invalid reference format"Fix Docker "invalid reference format" in CI - uppercase letters, spaces, double slashes, or unsubstituted "invalid reference format"Fix Docker "invalid reference format" in CI - an image name/tag with uppercase, illegal characters, an empty "manifest unknown"Fix Docker "manifest unknown" or "manifest for X not found" in CI - a tag or digest that was never pushed, "net/http: request canceled"Fix Docker "net/http: request canceled while waiting for connection (Client.Timeout exceeded)" in CI - a slow "pull access denied"Fix Docker "pull access denied for X, repository does not exist or may require 'docker login'" in CI - wrong "pull access denied ... repository does not exist"Fix Docker "Error response from daemon: pull access denied for <image>, repository does not exist or may "registry-mirrors" not appliedFix Docker registry mirror problems in CI - a configured registry-mirror that is ignored (only applies to "received unexpected HTTP status: 401/403"Fix Docker "received unexpected status code 401 Unauthorized / 403 Forbidden" from a registry in CI - a "x509: certificate signed by unknown authority"Fix Docker "x509: certificate signed by unknown authority" pushing or pulling in CI - a self-signed or containerd image store not enabledFix Docker features that need the containerd image store in CI - multi-platform --load, certain export/import "unsupported MediaType"Fix Docker push "manifest invalid: unsupported MediaType" / OCI-vs-Docker manifest errors in CI - a registry "repository does not exist" (ECR)Fix Docker push to Amazon ECR "name unknown: The repository ... "server gave HTTP response to HTTPS client"Fix "http: server gave HTTP response to HTTPS client" in CI - the docker daemon tried HTTPS but the registry

Run & resources

OOM kills, disk space, and exit codes.

"cannot enter cgroupv2"Fix Docker cgroup v2 errors in CI - "cannot enter cgroupv2", missing controllers, or runc failing to set up "container name is already in use"Fix Docker "Error response from daemon: Conflict. The container name ... "device or resource busy"Fix Docker "unlinkat ... device or resource busy" / "Error removing ... "error during connect: docker_engine"Fix Docker "error during connect ... open //./pipe/docker_engine: The system cannot find the file specified" "exec user process caused"Fix Docker "standard_init_linux.go: exec user process caused: no such file or directory" in CI - missing "failed to create shim task"Fix Docker "failed to create shim task: OCI runtime create failed ... "failed to create shim task"Fix "Error response from daemon: failed to create shim task" in CI - containerd could not spawn the shim/task "failed to set up container networking"Fix Docker "failed to set up container networking" in CI - iptables/bridge problems, exhausted address pools, "does not match platform"Fix Docker "image ... does not match the specified platform" / "image operating system linux cannot be used "read-only /var/lib/docker"Fix "Error response from daemon: mkdir /var/lib/docker: read-only file system" in CI - the daemon's data-root "mkdir /proc"Fix Docker "oci runtime error: container_linux.go: ... mkdir /proc: ..." in CI - the runtime could not set up "OCI runtime exec failed"Fix Docker "OCI runtime exec failed: exec failed: ... executable file not found in $PATH" in CI - a docker "permission denied ... /var/run/docker.sock"Fix the Docker "permission denied while trying to connect to the Docker daemon socket" error in CI, caused by "pull always but offline"Fix Docker pull failures with `--pull always` in CI when the runner is offline or air-gapped - the daemon "exec ... permission denied"Fix Docker "standard_init_linux.go: exec user process caused: permission denied" in CI - the entrypoint "invalid character in daemon.json"Fix dockerd failing to start in CI - "unable to configure the Docker daemon ...

Compose

Service, network, and dependency failures.

"Additional property ... is not allowed"Fix Docker Compose "Additional property X is not allowed" in CI - a misspelled or misindented key that fails "build context path missing"Fix "unable to prepare context: path <dir> not found" / "no such file or directory" for a compose service "external network ... could not be found"Fix Docker Compose "network X declared as external, but could not be found" in CI - an external network that "pull access denied" (compose)Fix Docker Compose "pull access denied for <image>, repository does not exist or may require docker login" in "service failed to build"Fix Docker Compose build failures in CI - bad build context, missing Dockerfile, dependency ordering, and "refers to undefined volume"Fix Docker Compose "service X refers to undefined volume Y" in CI - a named volume used by a service but "services.<name> must be a mapping"Fix Docker Compose "services.<name> must be a mapping" in CI - a service defined as a scalar or list instead "version is obsolete"Fix Docker Compose "the attribute `version` is obsolete, it will be ignored" surfacing as a CI failure - "version is obsolete"Understand the Docker Compose "the attribute version is obsolete" warning in CI - harmless, but a sign you "variable is not set"Fix Docker Compose "WARN: The X variable is not set. Defaulting to a blank string" in CI - an unset "variable is not set" / wrong defaultFix Docker Compose variable interpolation defaults in CI - ${VAR} empty when unset, the difference between :- "bind source path does not exist"Fix Docker Compose "error mounting ... bind source path does not exist" in CI - a relative bind-mount host

Explore other topics

GitHub ActionsWorkflow, runner, and YAML errors - diagnosed and fixed. Node.js & npmnpm, yarn, and pnpm failures in CI - solved. Pythonpip, poetry, venv, and pytest failures - fixed. Java & JVMMaven, Gradle, and JVM failures in CI - resolved. GoGo build, module, and test failures - diagnosed. RustCargo and toolchain failures in CI - fixed.