Critical severityconnection
MySQL Error:
2003
What does this error mean?
Error 2003 (CR_CONN_HOST_ERROR) means the MySQL client library could not open a TCP connection to the server on the specified host and port. The client sends a SYN packet and either gets no response (timeout after ~30 seconds), a RST (connection refused), or a DNS resolution failure. In data-pipeline context this typically surfaces when Azure Data Factory, Power BI Gateway, or a dbt run tries to reach a MySQL source and the network path is broken. The symptom in ADF is an immediate pipeline_failed status with error code 2003 in the activity output; in Power BI you see a dataset refresh failure with 'unable to connect to data source'. The root cause is always network-level — the MySQL process itself may be perfectly healthy.
Common causes
- 1MySQL server process (mysqld) is stopped, crashed, or still starting up — the TCP port is not listening at all.
- 2A firewall, Azure NSG, AWS Security Group, or VPC network ACL blocks inbound traffic on port 3306 (or the custom port) between the client machine and the MySQL host.
- 3The connection string contains a wrong hostname, a stale IP address, or a DNS name that does not resolve from the client's network (common after VM migrations or DNS TTL issues).
- 4MySQL's bind-address in my.cnf is set to 127.0.0.1, so the server only accepts connections from localhost and rejects remote TCP connections with a RST.
- 5MySQL is running on a non-default port (e.g. 3307) but the client still targets 3306 — common when multiple MySQL instances run on the same host.
- 6The self-hosted integration runtime or Power BI Gateway machine has no route to the MySQL server's private IP — missing VPN tunnel, peering, or private endpoint configuration.
- 7TCP connection timeout due to an intermediate proxy or load balancer (e.g. Azure Private Link, HAProxy) that silently drops the SYN when the backend pool is unhealthy.
How to fix it
- 1Step 1: SSH into the MySQL host and verify the process is running: `systemctl status mysql` (Debian/Ubuntu) or `systemctl status mysqld` (RHEL/CentOS). If stopped, check logs with `journalctl -u mysql -n 100` before restarting.
- 2Step 2: Confirm MySQL is listening on the expected interface and port: `ss -tlnp | grep 3306`. If the output shows 127.0.0.1:3306 instead of 0.0.0.0:3306, MySQL only accepts local connections.
- 3Step 3: Fix bind-address if needed — edit `/etc/mysql/mysql.conf.d/mysqld.cnf` (or `/etc/my.cnf` on RHEL), set `bind-address = 0.0.0.0` under `[mysqld]`, and restart: `sudo systemctl restart mysql`.
- 4Step 4: From the client machine (ADF self-hosted IR, Gateway, or dbt host), test TCP reachability: `telnet <mysql-host> 3306` on Linux, or `Test-NetConnection -ComputerName <mysql-host> -Port 3306` in PowerShell. A refused or timed-out connection confirms a network-level block.
- 5Step 5: Open the firewall — on the MySQL host: `sudo ufw allow from <client-ip> to any port 3306 proto tcp`. In Azure: add an inbound NSG rule for port 3306 from the IR subnet. In AWS: add an inbound Security Group rule for TCP 3306 from the client CIDR.
- 6Step 6: If using Azure Data Factory with a managed VNet, verify that the managed private endpoint for MySQL is approved and in a 'Succeeded' provisioning state in the Azure portal under ADF → Managed private endpoints.
- 7Step 7: After changes, trigger a test run: in ADF use 'Debug' on the pipeline; in Power BI Service go to Settings → Datasets → Refresh now; for dbt run `dbt debug` to confirm the connection profile works.
Example log output
ERROR 2003 (HY000): Can't connect to MySQL server on 'db-prod-mysql-01.internal' (110)
[ADF] Activity failed: {"errorCode":"2003","message":"Cannot connect to MySQL server. TCP connection to host 'db-prod-mysql-01.internal:3306' failed: Connection timed out.","failureType":"UserError"}
[dbt] Connection Error: 2003 (HY000): Can't connect to MySQL server on 'db-prod-mysql-01.internal' (111 Connection refused)