Error starting userland proxy: listen tcp 0.0.0.0:3306: bind: address already in use
When attempting to spin up a new Laravel project using Docker, specifically referencing older setups like dockervel, encountering the error Error starting userland proxy: listen tcp 0.0.0.0:3306: bind: address already in use is a classic port conflict issue. This message indicates that the Docker daemon tried to map your container's internal MySQL port (3306) to a host port, but that specific port on your machine was already occupied by another process.
In the scenario described, the user attempted to change the mapping in docker-compose.yml from 8084:80 to address similar conflicts, yet the error persisted specifically on port 3306. The confusion often arises because modifying the web server port (e.g., changing 80 to 8084) does not automatically resolve a conflict on the database port if that port remains bound to 0.0.0.0 on the host.
Understanding the Port Mapping Conflict
The error message is explicit: Docker cannot bind to tcp 0.0.0.0:3306. This usually happens when a MySQL service is already running locally, or if a previous container instance was not fully cleaned up. Even if you deleted the container named dockervel_mysql_1 manually, the underlying process occupying port 3306 might still be active in the background, or the port might be held by a different application entirely (such as an existing local development MySQL instance or a leftover service).
To resolve this, you must identify what is currently listening on port 3306. On Linux-based systems, you can run:
sudo netstat -tulpn | grep :3306
# Or alternatively
sudo lsof -i :3306
If a process is listed, you have two main options depending on your goal. If this existing MySQL instance is no longer needed for the new project, stop and remove it. If you are trying to run multiple database containers simultaneously, you must ensure they map to unique host ports.
Adjusting Docker Configuration Correctly
The initial attempt to fix the issue involved changing the web port in docker-compose.yml:
ports:
- "8084:80"
While this changes the HTTP interface, it does not affect the MySQL port configuration unless explicitly defined. If your docker-compose.yml (or Dockerfile derived from dockervel) defines a port mapping for MySQL as 3306:3306, you must change that specific line to map to a free port on your host, such as 3307:3306.
For example:
ports:
- "8084:80"
- "3307:3306"
By mapping the container's internal port 3306 to host port 3307, you prevent the conflict with any existing service bound to 3306. However, be aware that this will require updating your application's connection string (.env file) to point to 127.0.0.1:3307 instead of the default 127.0.0.1:3306.
Cleaning Up Residual Processes
In some cases, simply editing the configuration is insufficient because a previous container or process holds the port in an ESTABLISHED state even after the process exits. This often happens with Docker's "userland proxy." If you encounter persistent errors where ports appear free but Docker still complains, try restarting the Docker daemon:
sudo systemctl restart docker
This forces Docker to release any lingering file descriptors or network sockets associated with previous containers. Additionally, ensure that no other MySQL instances are running via system services (like mysqld) that might be automatically starting on boot and conflicting with your containerized environment.
Modern Alternatives to Legacy Images
The source material references dockervel, an image setup from 2015. While functional for legacy projects, modern Laravel development typically benefits from the official Docker images provided by the Laravel community or the broader ecosystem. These images often include built-in support for MySQL and PostgreSQL with sensible defaults that reduce the likelihood of port conflicts out of the box.
If you are starting a fresh project today, consider using a docker-compose stack that explicitly defines environment variables for database credentials and unique port mappings. For instance, the Laravel Company provides resources and tools to help streamline this setup, ensuring your development environment is isolated and conflict-free without requiring manual intervention on every port mapping.
Ultimately, the error is not a bug in Docker but a signal that the host machine's network stack is busy. By auditing what runs on port 3306 and explicitly remapping container ports to free ranges, you can avoid these interruptions and get your development environment running smoothly.
