Scalable Human Blog

TL;DR

A rogue Node.js process on your Mac can hijack port 3000, causing Docker containers to fail silently, but spotting it with lsof and killing the process restores smooth port forwarding.

Introduction

Ever fired up a Docker container only to watch your requests vanish into the void? If you’re developing on a Mac with tools like Colima, a sneaky port conflict from a lingering Node.js process might be the culprit. This post breaks down a real-world headache I encountered, explains why it happens, and shares simple fixes to get you back on track. You’ll walk away with practical tips to diagnose and prevent these issues, saving you hours of frustrated debugging.

Unpacking the Port Conflict

Picture this: You’re spinning up a Docker container that needs to expose port 3000 for your app. Everything seems set, but when you hit http://localhost:3000, the request connects… and then nothing. No response, no errors in your container logs, just endless waiting. Sound familiar? That’s exactly what happened to me, and it boiled down to a rogue Node.js process already squatting on that port.

What Went Wrong

On my Mac setup with Colima (which runs Docker in a lightweight VM), a forgotten Node process (PID 90878) was listening on port 3000 directly on the host machine. When my Docker container tried to map the same port, the host process won the race. Requests to localhost routed straight to this local Node instance instead of the container. The kicker? This process lacked the right routes or handlers, so it accepted the TCP connection but hung indefinitely without sending an HTTP response.

This explained the weird symptoms: successful connections (the TCP handshake worked), but timeouts on every request. Meanwhile, curling the endpoint from inside the Docker container worked perfectly, bypassing the host conflict entirely. No wonder the container logs stayed silent— the traffic never reached it!

Diagnosing the Issue

The breakthrough came from running lsof -i :3000, a handy command that lists processes using a specific port. It revealed the rogue Node process hogging the spot. On macOS with Colima, host processes take precedence over Docker port mappings, so this local listener effectively blocked the container’s exposure. If I’d skipped this check, I might have wasted time tweaking Docker configs or restarting services unnecessarily.

Fixing It Step by Step

Resolution was straightforward once I identified the offender. First, I killed the conflicting process with kill -9 90878 to free up the port. Then, a quick restart of Colima re-established proper port forwarding between the VM and my Mac. Boom—requests started hitting the Docker container as intended, and everything ran smoothly.

This isn’t just a one-off; it’s a reminder that background processes can linger from previous sessions, especially in Node.js development where servers might not shut down cleanly.

Key Takeaways

• Check for conflicts early: Before running docker-compose up, use lsof -i :3000 to spot any processes already using your target port.
• Understand precedence: On macOS with Colima, local host processes override Docker mappings, so always verify what’s running on the host.
• Kill with care: Use kill -9 <PID> for stubborn processes, but confirm the PID first to avoid disrupting unrelated apps.
• Test internally: If external requests fail, try accessing from inside the container to isolate host-side issues.
• Prevent repeats: Make it a habit to clean up Node processes after testing, perhaps with scripts or tools like pm2 for better management.

Conclusion

Port conflicts like this rogue Node.js process can turn a simple Docker setup into a debugging nightmare, but armed with tools like lsof and a quick kill command, they’re easy to squash. Next time you’re staring at timeouts, remember to peek under the hood of your host machine. Have you run into similar issues? Share your war stories in the comments—I’d love to hear how you tackled them!

📚 Further Reading & Related Topics
If you’re exploring fixing port conflicts from rogue Node.js processes on Mac, these related articles will provide deeper insights:
• Exploring JShell IntelliJ VSCode Extension and the Traditional Terminal – This post delves into using the traditional terminal for development tasks, which is essential for identifying and terminating rogue processes causing port conflicts on Mac.
• MacBook vs Windows Laptop for Software Development Making the Right Choice – This comparison highlights Mac-specific development environments, offering insights into tools and setups that can help troubleshoot issues like Node.js port conflicts.
• GitHub Copilot in the CLI Your New Best Friend for Terminal Commands – This article explores AI-assisted terminal commands, providing practical ways to efficiently manage and resolve process-related problems such as port conflicts on Mac.