01
Read the mapping from left to right
In 127.0.0.1:8081:8080, 127.0.0.1 is the host bind address, 8081 is the host port, and 8080 is the container port. If a listener already occupies the requested host endpoint, container startup can fail before your application handles any request.
By contrast, a container that starts but returns connection refused through its mapping may be targeting the wrong internal port or binding its application only to container loopback. These require a different fix from an allocated host port.
02
Locate the owner before touching it
List published ports on running containers and inspect the candidate service. An existing database, development server, or another Compose project may be using the endpoint intentionally. Do not stop it until you know whether it is safe to interrupt.
If no Docker container explains the conflict, inspect host listeners. On macOS, lsof can identify a local TCP listener. On Linux, ss is a common equivalent. With a remote Docker context, investigate the daemon host rather than assuming the port lives on your laptop.
docker ps --format 'table {{.Names}} {{.Ports}}'
docker compose ps
# Substitute an actual container name.
docker port your-api 8080/tcp
# macOS: inspect the host endpoint named in the error.
lsof -nP -iTCP:8081 -sTCP:LISTEN03
Reproduce the conflict in an isolated test
The following uses a chosen host port for the first container. Confirm that 58081 is free, or choose another free loopback port. Start the second container with the same value to reproduce the conflict. Use unique test names if these example names already exist.
In the editorial lab the duplicate mapping failed, while a second automatically allocated host port succeeded. Both HTTP processes continued to use container port 8080. The test did not require changing the server code.
# Choose a free host port for this isolated example.
demo_port=58081
docker run --detach --name port-demo-one -p "127.0.0.1:$demo_port:8080" python:3.12-slim python -m http.server 8080 --bind 0.0.0.0
docker port port-demo-one 8080/tcp
# Expected failure: same host IP, TCP port, and protocol.
docker run --detach --name port-demo-two -p "127.0.0.1:$demo_port:8080" python:3.12-slim python -m http.server 8080 --bind 0.0.0.004
Change the intended endpoint, then test it
For a stable local URL, choose a free host port in the Compose ports entry. For a throwaway test, let Docker assign the host port and discover it with docker port. Keep a loopback bind for a service intended only for your computer.
Recreate the affected container, inspect its new mapping, then request the reported endpoint. A mapping in inspect output is only configuration evidence; an HTTP response confirms that the application is reachable through it.
# Example Compose mapping: "127.0.0.1:8082:8080"
docker compose up --detach --no-deps api
docker compose ps api
# Use the host port actually configured or reported.
curl --fail http://127.0.0.1:8082/05
Close the test without interrupting other projects
When the experiment is complete, remove only the two containers you created, including a second container left in Created state after a failed start. Avoid global cleanup commands for a single-port conflict.
If containers communicate only inside their Docker network, ask whether the service needs a host publication at all. Removing an unnecessary publication reduces host-port conflicts; it does not change the service port used by peer containers.
docker rm --force port-demo-one port-demo-twoSınırları bil
The reproduction uses two disposable Python HTTP containers with TCP port 8080 and host loopback publishing. Exact error wording varies by Docker Engine and Desktop version. Host processes can also own the port; Docker-only listings cannot exclude that case. Reproduction checked on 26 October 2026 using Linux containers on Docker Engine 29.6.2 and Compose 5.3.1; this is the validation environment, not a minimum-version claim.
Kaynaklar ve ileri okuma
CoreTrailKit tarafından hazırlanan teknik yayın.
Bütün yazıları keşfet