TIL: How to Fix the "Port Already in Use" Error in Docker
We have all been there. You just built a fresh Docker image, you confidently type your docker run command into the terminal, and BAM. You are hit with a massive wall of red text that looks something like this:
Error starting userland proxy: listen tcp4 0.0.0.0:3000: bind: address already in use.
This error (often referred to as EADDRINUSE) simply means that something else on your computer is already using the port you are trying to assign to your Docker container.
Today I Learned (TIL) the fastest way to find that rogue process and terminate it so you can get back to coding. Here is the two-step fix for Mac and Linux users.
Step 1: Find the Rogue Process
To find out exactly which application is hoarding your port, we will use the lsof (List Open Files) command.
Open your terminal and type this command, replacing 3000 with whatever port is giving you trouble:
lsof -i :3000
This will return a list of processes using that port. Look under the PID (Process ID) column. You need that number.
Step 2: Kill the Process
Now that we have the Process ID, we can force it to shut down using the kill command. Pass the -9 flag to ensure it terminates immediately, followed by the PID you found in Step 1:
kill -9 14235
That’s it! Your port is now free. You can run your docker run -p 3000:3000 my-app command again, and it will spin up perfectly.
Bonus: What if it's a "Ghost" Docker Container?
Sometimes, the port is being blocked because you started a Docker container earlier, forgot about it, and left it running in the background.
If lsof doesn't solve your problem, quickly check your active Docker containers:
docker ps
Find the container using your port, grab its Container ID, and stop it gracefully:
docker stop <CONTAINER_ID>
📚 Catch up on this Docker Series:
If this quick tip saved you some debugging time today, you can ☕ buy me a coffee here to support my work!