Fixing Docker‑Compose, PhpStorm & Xdebug: Lesson from a Port & Socket Mix‑up

I recently hit a frustrating edge‑case with Docker, PhpStorm and Xdebug - and wanted to walk through what happened and how I fixed it, in case you end up in the same situation.

The symptom: “ports are not available” on port 3306

It started simple enough - Docker failed to start my MySQL container:

Error response from daemon: ports are not available: exposing port TCP 0.0.0.0:3306 -> 127.0.0.1:0: listen tcp […] bind: address already in use

I ran:

sudo netstat -tulnp | grep 3306

which showed:

tcp  0.0.0.0:3306  LISTEN  6885/docker-proxy

That meant Docker itself was already proxying 3306 - likely due to another container still running. So I:

• Ran docker ps which shows no container running
• Ran sudo docker ps which showed the MySQL container running on port 3306
• Stopped and removed it with sudo docker compose down

That immediately solved the port conflict.

Next: PhpStorm could no longer run PHPUnit tests via Docker

I then ran, as my local user chris:

docker compose down
docker compose up

And all the containers started as expected. But now when I ran my tests in PhpStorm they failed with:

Failed to start docker‑compose service, start it in a command line and try again.

Yet everything worked fine from the CLI. What changed?

Turns out the issue wasn’t ports - it was the Docker socket PhpStorm was using.

The root cause: a user‑specific Docker socket

Running:

docker context inspect

revealed the CLI was talking to:

unix:///home/ubuntu/.docker/desktop/docker.sock

instead of the default:

/var/run/docker.sock

That meant Docker was running under my username (e.g. via Linux/WSL’s Docker Desktop), not the system socket. PhpStorm was still trying to connect to var/run/docker.sock, so none of the containers it saw were the ones I just started.

How I fixed it

Point PhpStorm at the right socket

In PhpStorm settings → Build, Execution, Deployment → Docker:

• Edited the Docker configuration.
• Changed the Unix socket to:

unix:///home/chris/.docker/desktop/docker.sock

Reconfigure PhpStorm’s interpreter & test runner

Now with PhpStorm connected to the correct Docker instance:

• Went to Settings → PHP → CLI Interpreters
• Removed any old Docker‑based interpreters tied to the wrong socket.
• Added a new one pointing at my service’s PHP container.
• Verified Settings → PHP → Test Frameworks recognized it.

Summary

Major takeaways:

• Port conflicts? Check which docker‑proxy is listening and remove the conflicting container or change the host port.
• PhpStorm not seeing running containers? Make sure it’s hooked to the same socket that docker CLI is.
• Always start containers and IDEs under the same user and context.
• If you switch Docker setups (e.g. system vs Desktop), update PhpStorm’s Docker settings accordingly.

I hope this helps if you find yourself stuck a few steps removed from the real issue. Let me know if you’re still facing Xdebug or interpreter mapping problems - I’ve walked through quite a few of those myself lately!

Originally published at https://chrisshennan.com/blog/fixing-docker-compose-phpstorm-and-xdebug-lesson-from-a-port-and-socket-mix-up