MySQL Error 2005: CR_UNKNOWN_HOST - How to Fix and Prevent

What does “Unknown MySQL server host” mean?

MySQL raises Error 2005 (CR_UNKNOWN_HOST) when the client library cannot translate the host string you passed to a valid IP address. The TCP connection never starts, so authentication and SQL execution do not occur.

The message includes the failing host value and a system errno.

These details point to DNS or networking layers, not the MySQL daemon itself.

When does Error 2005 usually appear?

It appears immediately after a mysql, mysqldump, JDBC, or Python connector call that contains a typo, stale DNS entry, or blocked outbound port 3306.

Cloud VMs with custom DNS or VPNs often surface the issue.

Local development can also trigger the error if /etc/hosts or Windows hosts entries are missing for aliases like mysql.local.

How do I fix MySQL Error 2005?

Start by pinging the hostname from the same machine. If ping fails, check DNS or the hosts file. If ping succeeds, verify your MySQL port and firewall.

Finally, replace the hostname with a verified IP address to isolate name-resolution problems.

Updating connection strings in ORM configs, Docker compose files, or Kubernetes Secrets prevents the error across deployments.

Common scenarios and solutions

In Docker, the service name must match the container’s network alias.

Using “localhost” inside one container fails; use the service alias instead.

For AWS RDS, ensure the VPC DNS resolver is enabled and that your security group allows outbound DNS requests (port 53) and MySQL (3306).

Best practices to avoid CR_UNKNOWN_HOST

Store hostnames in environment variables managed by your CI/CD. Validate them during health checks.

Monitor DNS latency and failures with tools like dig or nslookup inside your application container.

With Galaxy, test queries directly in the editor; failed connections surface instantly, letting you correct host settings before committing code.

.