Connection refused when running Laravel artisan command with Docker

Connection refused when running Laravel artisan command with Docker

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Connection refused when running Laravel artisan command with Docker

When you can hit http://localhost:8888 and see the Blade welcome screen, but php artisan migrate immediately throws an SQLSTATE[HY000] [2002] Connection refused error, the web server is working but your PHP CLI process cannot talk to the database. This specific stack trace indicates that the TCP connection attempt failed before any handshake could occur.

In a Docker environment, this usually means the PHP process inside the app container literally cannot reach the mysql container on port 80. Your .env file shows DB_HOST=mysql, which relies on Docker's internal DNS resolution. For this to work, two conditions must be met: the containers must be on the same network, and the database service must be ready to accept connections when the PHP process attempts to connect.

The error persists even if you try fiddling with host parameters in your .env file because the root cause is often a race condition or a network visibility issue rather than an incorrect hostname.

The Race Condition Trap

Laravel 5.4 applications typically start up by initializing the web server (Apache, in your case). However, the php artisan migrate command runs outside of the web request lifecycle. When you run the command from your terminal or via a script, it executes immediately after the container starts.

There is a high probability that when your app container starts, the mysql container is still initializing. Docker's depends_on directive in your docker-compose.yml ensures that the app container waits for the mysql container to be "ready" (healthy), but it does not guarantee that the database application itself has finished starting up and accepting connections on port 80.

The depends_on configuration you provided:

app:
  depends_on:
    - mysql

This is insufficient for reliable migrations. You need a health check to ensure the MySQL service is actually listening before attempting to connect. Without this, the PHP CLI process might try to connect milliseconds after the database container has just launched, resulting in a "Connection refused" error because the socket isn't open yet.

To resolve this, update your docker-compose.yml to include a health check for the MariaDB service:

services:
  mysql:
    image: mariadb:latest
    ports:
      - 8889:80
    environment:
      MYSQL_ROOT_PASSWORD: 'dev'
      MYSQL_DATABASE: 'dev'
      MYSQL_USER: 'dev'
      MYSQL_PASSWORD: 'dev'
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 5s
      retries: 5
      timeout: 5s

  app:
    container_name: laravel_app
    image: webdevops/php-apache-dev:ubuntu-16.04
    links:
      - mysql
    depends_on:
      - mysql
    ports:
      - 8888:80
    volumes:
      - .:/app
    environment:
      docker: 'true'
      WEB_DOCUMENT_ROOT: '/app/public'
      WEB_NO_CACHE_PATTERN: '\.(.*)$$'
      working_dir: '/app'

By adding the healthcheck, Docker will wait for the mysql container to successfully run the health check script (which verifies the connection and InnoDB initialization) before starting the app container. This ensures that when you run php artisan migrate or when the web server starts, the database is fully ready.

Network Isolation and Hostnames

Another common pitfall involves the network configuration. Your .env file correctly uses DB_HOST=mysql. This relies on Docker's internal DNS, which automatically resolves service names to IP addresses within the same network overlay or bridge.

If you are running this on a single machine without custom networking, the default bridge network is shared between containers, so DNS resolution should work. However, if you encounter issues where mysql resolves but the connection is refused, check if you have inadvertently set DB_HOST=127.0.0.1 or localhost. Inside a container, localhost refers to the container's own network namespace, not the host machine. If your database container listens only on 127.0.0.1, external connections will be refused unless you bind it to 0.0.0.0.

The image webdevops/php-apache-dev:ubuntu-16.04 is a legacy image for Laravel 5.4. While it works, modern Laravel applications (Laravel 8+) often utilize separate CLI and Web containers or more robust database images like mariadb:10.x. If you are maintaining a legacy stack, ensure that the links directive is still respected. In newer Docker versions, explicit network attachment is preferred over links, though links usually suffices for simple setups.

If you continue to face connection issues despite correct health checks and hostnames, inspect the logs of both containers:

docker-compose logs mysql
docker-compose logs app

The MySQL logs will reveal if it is actually listening on port 80 or if there are startup errors preventing it from accepting connections. The PHP CLI logs (if any) might show connection timeouts before finally throwing the "refused" error, indicating a timing issue that a health check solves definitively.

Our network