MySQL "ERROR 2003 (HY000): Can't connect to MySQL server on host" in CI

By Daniel Zoghalchali·Latchkey

The MySQL client could not establish a TCP connection to the server (errno 111 = Connection refused). MySQL is not accepting connections on that host/port yet, or the address is wrong - a reachability problem, not authentication.

What this error means

mysql/migrate fails with "ERROR 2003 (HY000): Can't connect to MySQL server on host 'db' (111)". It frequently passes on retry once the MySQL container finishes initializing.

ERROR 2003 (HY000): Can't connect to MySQL server on 'db' (111)

Common causes

MySQL not ready yet

MySQL initialization (especially first boot) takes time; connecting before it is ready is refused. This is transient.

Wrong host or port

A host/port that does not match the reachable service refuses every attempt the same way.

Transient network blip

A brief connectivity drop can refuse a connection that succeeds moments later.

How to fix it

Wait for MySQL before connecting

Block on a ping until the server answers.

until mysqladmin ping -h 127.0.0.1 -P 3306 --silent; do sleep 1; done
mysql -h 127.0.0.1 -uroot -p"$MYSQL_PWD" -e 'select 1'

Add a healthcheck to the service

services:
  mysql:
    image: mysql:8
    env: { MYSQL_ROOT_PASSWORD: root }
    options: >-
      --health-cmd "mysqladmin ping -h 127.0.0.1"
      --health-interval 5s --health-retries 12

How to prevent it

• Gate MySQL connections on mysqladmin ping or a healthcheck.
• Keep host/port aligned with the CI network.
• On managed runners (Latchkey), self-healing auto-retries transient failures such as MySQL being briefly slow to accept connections.

Frequently asked questions

Related guides

References

• GitHub Actions documentation