Docker Error Messages: Causes and Fixes (With Real Output)

This page collects common Docker error messages. Each heading is a keyword from the error message, so you can use your browser's search function (Ctrl+F) to find it. Every error includes output reproduced with Docker 29, its cause, and a fix.

If you can't find your error, start with these basic troubleshooting steps:

1. Check the keyword in the last part of the error message.
2. Use docker ps -a to check the container status and exit code.
3. Use docker logs container-name to see the program's own output.
4. See Viewing logs and debugging for detailed debugging steps.

Connections and permissions

failed to connect to the docker API / Cannot connect to the Docker daemon

$ docker run --rm --entrypoint docker docker:29.9-cli -H unix:///var/run/docker.sock ps
failed to connect to the docker API at unix:///var/run/docker.sock; check if the path is correct and if the daemon is running: dial unix /var/run/docker.sock: connect: no such file or directory

Older versions showed Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?. The meaning is the same: the docker command (client) can't find Docker Engine (server).

Fix:

• Windows / macOS: Make sure Docker Desktop is running. The whale icon in the system tray should stop spinning, and the status should say Engine running.
• Linux: Start the Docker service with sudo systemctl start docker, and enable it at startup with sudo systemctl enable docker.
• Check whether the DOCKER_HOST environment variable is set or whether you switched to another context: docker context ls.

permission denied while trying to connect to the docker API

$ docker run --rm -u 1000:1000 -v /var/run/docker.sock:/var/run/docker.sock docker:29.9-cli docker ps
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

On Linux, only root and members of the docker group can access /var/run/docker.sock. Regular users see this error when they run docker.

Fix: Add your user to the docker group, then log out and back in (or run newgrp docker) for the change to take effect:

sudo usermod -aG docker $USER

Membership in the docker group is equivalent to root access. See Security best practices for why. To avoid this, you can use Rootless mode.

Ports and names

port is already allocated

$ docker run -d --name web1 -p 8080:80 nginx:1.30-alpine
7a72d42f052dfebded509314b1975c72fbb1fcbf0c97099d6d60c9dedbcad8a1

$ docker run -d --name web2 -p 8080:80 nginx:1.30-alpine
6bcca59a67e5a5adbab1da7b2dbb7ef92f1df1f6e7680462a22541fd96f0ac9f
docker: Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint web2 (3a269ae1baae56a10b06552ba76fff69b3414885b2fa7a737344e081b4d5acd5): Bind for 0.0.0.0:8080 failed: port is already allocated

Run 'docker run --help' for more information

Port 8080 on the host is already in use by another container (in this example, web1). Note that when the error occurs, web2 has already been created but hasn't started (its status is Created). If you simply run the same command again after fixing the issue, you'll get another error: the name is already in use.

Fix:

• Use a different host port: -p 8081:80.
• Or stop the container using the port: use docker ps to find what's using 8080, then run docker stop.
• Remove the container that failed to start: docker rm web2.

address already in use

$ docker run -d --name web3 -p 9090:80 nginx:1.30-alpine
2c4649bbf85211d1ef6852c95fad52075b63d8d77e3fcd7c74db0bc7d15fbd8f
docker: Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint web3 (38386ef2562f999706b1d2b00eac0e48125eb006916dc857832ce18d36fe44d6): failed to bind host port 0.0.0.0:9090/tcp: address already in use

Run 'docker run --help' for more information

This is similar to the previous error, but the port is in use by another program on the host, not a container. For example, Nginx or MySQL may already be installed locally, or a development server may be running.

Fix: Find and stop the program using the port, or choose another port.

sudo lsof -i :9090          # Linux / macOS
netstat -ano | findstr 9090 # Windows

The container name "/web1" is already in use

$ docker run -d --name web1 -p 8081:80 nginx:1.30-alpine
docker: Error response from daemon: Conflict. The container name "/web1" is already in use by container "7a72d42f052dfebded509314b1975c72fbb1fcbf0c97099d6d60c9dedbcad8a1". You have to remove (or rename) that container to be able to reuse that name.

Run 'docker run --help' for more information

Container names must be unique, including names of stopped containers.

Fix:

• Remove the old container: docker rm -f web1.
• Or choose another name.
• Add --rm to one-off containers to remove them automatically when they exit, so they don't leave behind a container with the same name.

Images

not found / manifest unknown / pull access denied

$ docker pull nginx:9.99
Error response from daemon: failed to resolve reference "docker.io/library/nginx:9.99": docker.io/library/nginx:9.99: not found

$ docker pull ngnix-official-not-real
Using default tag: latest
Error response from daemon: failed to resolve reference "docker.io/library/ngnix-official-not-real:latest": docker.io/library/ngnix-official-not-real:latest: not found

The image can't be found. Common causes:

• The tag is misspelled or doesn't exist: There is no nginx:9.99 version. Check the Tags page on Docker Hub, or run docker buildx imagetools inspect image-name.
• The name is misspelled: ngnix. Official image names don't have a prefix, for example nginx and postgres.
• You aren't logged in to the private image registry: Run docker login first.

Depending on the Docker version and registry, the same problem may show as manifest unknown or pull access denied for ..., repository does not exist or may require 'docker login'.

repository name must be lowercase / invalid reference format

$ docker build -t MyApp .
ERROR: failed to build: invalid tag "MyApp": repository name must be lowercase

Image names can contain only lowercase letters, numbers, and -, _, ., and /. Change MyApp to myapp. If the name contains spaces or an extra colon (for example, myapp::1.0), Docker reports invalid reference format.

toomanyrequests: You have reached your pull rate limit

Docker Hub limits image pulls when you're not logged in. You'll hit the limit if you pull many images in a short time, for example when CI downloads them again on every run. This error wasn't reproduced in the tutorial environment, so the error text is based on the official documentation.

Fix:

• Log in to Docker Hub with docker login to get a higher limit.
• Use a cache in CI, or use an image mirror from another registry.
• You don't need to pull images that are already on your machine. Avoid adding --pull always to commands unnecessarily.

exec format error

The image's CPU architecture doesn't match the host. For example, an arm64 image built on an Apple Silicon Mac is running on an amd64 server. See Multi-platform images for actual output and fixes.

Container startup failures

exec /entrypoint.sh: no such file or directory (even though the file exists)

This happens most often to Windows users: the shell script was saved with Windows line endings (CRLF).

$ docker build -q -t crlf-demo .
sha256:194d0a73ff66c601a1e7b1bf80417ae47c5de6e5e076415f17b483e642929fc2

$ docker run --rm crlf-demo
exec /entrypoint.sh: no such file or directory

$ od -c entrypoint.sh | head -n 2
0000000   #   !   /   b   i   n   /   s   h  \r  \n   e   c   h   o    
0000020   "   h   e   l   l   o       f   r   o   m       e   n   t   r

od -c shows that the first line ends with \r \n. Linux reads the interpreter as /bin/sh\r (with an invisible extra \r). That program doesn't exist, so Docker reports no such file or directory, which is very misleading.

Fix:

• Change the line endings to LF in your editor (in VS Code, click CRLF in the lower-right corner and change it to LF).

• Git converts line endings to CRLF by default on Windows. Add .gitattributes to the project root to always use LF for scripts:

  *.sh text eol=lf

• Or convert the file in the Dockerfile: RUN sed -i 's/\r$//' /entrypoint.sh.

exec: "/entrypoint.sh": permission denied

$ docker build -q -t noexec-demo .
sha256:4f37fec89287104ccf6b509fef5c1836d2a1a65b36d858ff63b95fecc3340a0e

$ docker run --rm noexec-demo
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: exec: "/entrypoint.sh": permission denied

Run 'docker run --help' for more information

The script doesn't have execute permission. Windows filesystems don't have Linux execute permissions, so this is especially common when building from Windows.

Fix: Add execute permission in the Dockerfile:

COPY --chmod=755 entrypoint.sh /entrypoint.sh

Or run chmod +x entrypoint.sh on Linux / macOS before building.

executable file not found in $PATH

$ docker run --rm alpine:3.23 bash
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: exec: "bash": executable file not found in $PATH

Run 'docker run --help' for more information

The program isn't in the container. The alpine image doesn't include bash, only sh.

Fix: Use sh, or install bash in the Dockerfile with RUN apk add --no-cache bash. This also commonly happens when the program name in CMD is wrong or the program wasn't copied into the image.

Container starts and immediately exits (0)

$ docker run -d --name u1 ubuntu:26.04
9ff7034514a469602b48cc1bb3758514b32af8de6c602ce1bee11cd85813671c

$ docker ps -a --filter name=u1 --format "table {{.Names}}\t{{.Status}}"
NAMES     STATUS
u1        Exited (0) 2 seconds ago

$ docker rm u1
u1

This isn't an error: a container stops when its main process exits. The default command in the ubuntu image is bash. When it runs in the background (-d) without a terminal, bash can't read input and exits.

Fix:

• To interact with it: docker run -it ubuntu:26.04 bash.
• To keep it running: give it a program that doesn't exit, such as a web server. For testing, you can use sleep infinity.
• If the exit code isn't 0, check docker logs for the program's error message.

Exited (137) or OOMKilled

Exit code 137 means the container was forcefully stopped with SIGKILL (128 + 9). Common causes:

• Insufficient memory: The container exceeded its --memory limit or the host ran out of memory, so the system stopped it. Check with docker inspect -f "{{.State.OOMKilled}}" container; true means it ran out of memory.
• The program didn't exit after docker stop waited 10 seconds, so it was forcefully stopped. See the PID 1 test in Node.js applications.
• docker kill or docker rm -f.

The test host used in this tutorial doesn't have a swap limit enabled, so insufficient memory couldn't be reproduced reliably. That's why no actual output is included for this case.

cannot attach stdin to a TTY-enabled container because stdin is not a terminal / the input device is not a TTY

$ docker run -d --name a1 alpine:3.23 sleep 300
55637ca715821720e55fa1366d8df8813915bf12b7520f65b9e85922ea7c475c

$ docker exec -it a1 bash
cannot attach stdin to a TTY-enabled container because stdin is not a terminal

-t requests a terminal, but the current input isn't a terminal. This commonly happens when you use docker exec -it in a script, CI, or cron, or pass a file to the container with < or |.

Fix: For non-interactive use, remove -t. Keep only -i when you need to pass input, or use neither option. For example, use docker exec -i to restore a database.

Building (docker build)

failed to read dockerfile: open Dockerfile: no such file or directory

$ docker build -t x .
#0 building with "default" instance using docker driver

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 2B done
#1 DONE 0.0s
ERROR: failed to build: failed to solve: failed to read dockerfile: open Dockerfile: no such file or directory

There is no Dockerfile in the current directory.

Fix:

• Make sure you're in the right directory. The final . is the path to the build context.
• The filename must be Dockerfile (matching capitalization, with no extension). Windows Notepad may automatically add .txt, making the filename Dockerfile.txt.
• If the file has a different name, specify it with -f: docker build -f Dockerfile.dev ..

failed to calculate checksum ... not found (COPY can't find the file)

$ docker build -t copy-demo .

[+] Building 0.1s (6/6) FINISHED                                                                                                       docker:default
 => [internal] load build definition from Dockerfile                                                                                             0.0s
 => => transferring dockerfile: 88B                                                                                                              0.0s
 => WARN: CopyIgnoredFile: Attempting to Copy file "config.json" that is excluded by .dockerignore (line 2)                                      0.0s
 => [internal] load metadata for docker.io/library/alpine:3.23                                                                                   0.0s
 => [internal] load .dockerignore                                                                                                                0.0s
 => => transferring context: 52B                                                                                                                 0.0s
 => [internal] load build context                                                                                                                0.0s
 => => transferring context: 2B                                                                                                                  0.0s
 => CACHED [1/2] FROM docker.io/library/alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0                      0.0s
 => => resolve docker.io/library/alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0                             0.0s
 => ERROR [2/2] COPY config.json /app/config.json                                                                                                0.0s
------
 > [2/2] COPY config.json /app/config.json:
------

 1 warning found (use docker --debug to expand):
 - CopyIgnoredFile: Attempting to Copy file "config.json" that is excluded by .dockerignore (line 2)
Dockerfile:2
--------------------
   1 |     FROM alpine:3.23
   2 | >>> COPY config.json /app/config.json
   3 |
--------------------
ERROR: failed to build: failed to solve: failed to compute cache key: failed to calculate checksum of ref v1wocdfz4uxsgxp2q2kukkuqp::jww9anqv7tl0n3ksy
1tlwp8fv: "/config.json": not found

The file used by COPY isn't in the build context. The WARN: CopyIgnoredFile at the top already explains why: .dockerignore excluded config.json.

Common causes:

• The file is excluded by .dockerignore (Docker 29 shows a warning first).
• The path is wrong, or the file is outside the build context (the final . in docker build). COPY ../file can't access a parent directory.
• The capitalization doesn't match. Windows and macOS are case-insensitive; Linux is case-sensitive.

RUN ... did not complete successfully: exit code: 1

A RUN command failed during the build. Look at the output between the ------ lines above; that's the command's own error message. For example, collectstatic in Django can fail if STATIC_ROOT isn't set, as described in Python applications. Add --progress plain if you can't see the full output.

Volumes and networks

volume is in use

$ docker volume create data
data

$ docker run -d --name holder -v data:/data alpine:3.23 sleep 300
38eb68e3f9c7020fdb86ded25f1e73dc0a9fdcb932dea1353d04c4474e0e50d7

$ docker volume rm data
Error response from daemon: remove data: volume is in use - [38eb68e3f9c7020fdb86ded25f1e73dc0a9fdcb932dea1353d04c4474e0e50d7]

$ docker rm -f holder
holder

$ docker volume rm data
data

The Volume is still in use by a container (including stopped containers), so it can't be removed. The ID in the error message belongs to the container using it. Remove the container first, then remove the Volume.

network ... not found

$ docker run --rm --network appnet alpine:3.23 true
docker: Error response from daemon: failed to set up container networking: network appnet not found

Run 'docker run --help' for more information

The specified network doesn't exist. Create it with docker network create appnet, or check the name with docker network ls. Compose project networks are prefixed with the project name, for example, shop_default.

invalid mount config for type "bind": bind source path does not exist

This happens when you use --mount type=bind to mount a host path that doesn't exist. See Volumes and data persistence for actual output and how this differs from -v.

Docker Compose

yaml: ... did not find expected key / mapping values are not allowed

$ docker compose config
go-yaml load error in parser (while parsing a block mapping) at L3.C5-L6.C6: did not find expected key

There's an error in the YAML indentation. In this example, environment: is indented one space too far. The L3.C5-L6.C6 in the error message means the problem is in the block between line 3, column 5, and line 6, column 6.

Fix:

• Use spaces for indentation, not tabs.
• Align keys at the same level.
• Run docker compose config to check the file. If there are no errors, it prints the complete configuration in a normalized format.

depends on undefined service

$ docker compose up -d
service "app" depends on undefined service "db": invalid compose project

depends_on refers to a service that doesn't exist. Usually the name is misspelled, or the service is in a profiles section that hasn't been enabled.

The "DB_PASSWORD" variable is not set. Defaulting to a blank string.

$ docker compose config
time="2026-10-13T05:27:10Z" level=warning msg="The \"DB_PASSWORD\" variable is not set. Defaulting to a blank string."
name: c3
services:
  db:
    environment:
      POSTGRES_PASSWORD: ""
    image: postgres:18
    networks:
      default: null
networks:
  default:
    name: c3_default

This is a warning, not an error, but it can be dangerous: compose.yaml uses ${DB_PASSWORD}, but the variable isn't set in .env or the environment, so it's replaced with an empty string. The database may then initialize with no password.

Fix: Set the variable in .env, or use ${DB_PASSWORD:?DB_PASSWORD is required} to stop with an error if it isn't set. See Environment variables and .env files.

dependency failed to start: container ... is unhealthy

$ docker compose up -d
[+] up 3/3
 ✔ Network c4_default Created                                                                                                                     0.0s
 ✘ Container c4-db-1  Error dependency db failed to start                                                                                         2.8s
 ✔ Container c4-app-1 Created                                                                                                                     0.0s
dependency failed to start: container c4-db-1 is unhealthy

depends_on is set to condition: service_healthy, but the dependency's health check keeps failing. In this example, the health check deliberately runs false.

Troubleshooting:

• Run docker inspect --format "{{json .State.Health}}" container to see the output from each health check.
• Check that the health check command is correct, including the password and hostname. See MySQL and PostgreSQL for database health check examples.
• For slow-starting services, increase start_period and retries.

Disk space

No space left on device

$ docker run --rm --tmpfs /data:size=1m alpine:3.23 dd if=/dev/zero of=/data/big bs=1M count=2
dd: error writing '/data/big': No space left on device
2+0 records in
1+0 records out
1048576 bytes (1.0MB) copied, 0.001369 seconds, 730.5MB/s

There's not enough space where you're writing. This example uses a 1 MB tmpfs to demonstrate the issue inside a container. In practice, the more common cause is Docker's data directory on the host running out of space, which can produce the same error when building or pulling an image.

Fix:

• Run docker system df to see what's using space, then clean up as described in Cleaning up disk space.
• Check whether container logs are too large, and set a log size limit.
• In Docker Desktop, go to Settings → Resources and increase the virtual disk limit.

Windows-specific errors

The following examples were run with PowerShell 7.4. (To test everything in the same environment, they use the official PowerShell image to run pwsh in a container, so each command starts with docker run ... pwsh -Command.) The error text in Windows PowerShell 5.1 is slightly different, but the cause is the same.

Variable reference is not valid. ':' was not followed by a valid variable name character

$ docker run --rm -e NO_COLOR=1 -w /home/me/project mcr.microsoft.com/powershell:latest pwsh -NoProfile -Command '$PSStyle.OutputRendering="PlainText"; mkdir /home/me/project -Force | Out-Null; Set-Location /home/me/project; Write-Output "$(pwd)/site:/app"; Write-Output "${PWD}/site:/app"'

/home/me/project/site:/app
/home/me/project/site:/app

$ docker run --rm -e NO_COLOR=1 -w /home/me/project mcr.microsoft.com/powershell:latest pwsh -NoProfile -Command '$PSStyle.OutputRendering="PlainText"; Write-Output "$PWD:/app"'
ParserError:
Line |
   1 |  $PSStyle.OutputRendering="PlainText"; Write-Output "$PWD:/app"
     |                                                      ~~~~~
     | Variable reference is not valid. ':' was not followed by a valid
     | variable name character. Consider using ${} to delimit the name.

In PowerShell, "$PWD:/app" causes an error because PowerShell treats $PWD: as special variable syntax. Change it to "${PWD}:/app". The "$(pwd)/site:/app" form also works in PowerShell (the first command prints the same two lines).

See Your first container for a complete comparison of Windows commands.

The '<' operator is reserved for future use

$ docker run --rm -e NO_COLOR=1 -w /home/me/project mcr.microsoft.com/powershell:latest pwsh -NoProfile -Command '$PSStyle.OutputRendering="PlainText"; docker exec -i mysql mysql app < app.sql'
ParserError:
Line |
   1 |  … OutputRendering="PlainText"; docker exec -i mysql mysql app < app.sql
     |                                                                ~
     | The '<' operator is reserved for future use.

PowerShell doesn't support using < to redirect a file into a command, so the docker exec -i ... < backup.sql command used to restore a database in tutorials won't work in PowerShell.

Fix: Use docker cp to copy the file into the container, then import it from inside the container. This works on every system and avoids the issue in PowerShell 5.1 where > saves files as UTF-16. Here's an example with PostgreSQL:

$ docker compose exec db psql -U app -c 'CREATE TABLE t (id int); INSERT INTO t VALUES (1),(2);'
CREATE TABLE
INSERT 0 2

$ docker compose exec db pg_dump -U app -Fc -f /tmp/app.dump app

$ docker compose cp db:/tmp/app.dump app.dump
 pgwin-db-1 Copying pgwin-db-1:/tmp/app.dump to app.dump
 pgwin-db-1 Copied pgwin-db-1:/tmp/app.dump to app.dump

$ ls -l app.dump
-rw-rw-rw-    1 root     root          1251 Oct 13 05:30 app.dump

$ docker compose exec db psql -U app -c 'DROP TABLE t;'
DROP TABLE

$ docker compose cp app.dump db:/tmp/restore.dump
 pgwin-db-1 Copying app.dump to pgwin-db-1:/tmp/restore.dump
 pgwin-db-1 Copied app.dump to pgwin-db-1:/tmp/restore.dump

$ docker compose exec db pg_restore -U app -d app /tmp/restore.dump

$ docker compose exec db psql -U app -c 'SELECT count(*) FROM t;'
 count
-------
     2
(1 row)

See the backup section in MySQL for the MySQL command.

Recap

• Start with the keyword at the end of the error message, then use docker ps -a and docker logs to check the status.
• When a port is in use or a name conflicts, the failed container may already have been created. Remember to run docker rm.
• On Windows, scripts need LF line endings and execute permission. Otherwise, Docker may show the misleading no such file or directory or permission denied errors.
• For Compose problems, start with docker compose config.
• In PowerShell, use ${PWD} and avoid using < to redirect a file.

Updated October 13, 2026