Skip to content

inchTodd/db-error-troubleshooting-skills / skills/mysql-2003

mysql-2003

Unverified

排查 MySQL 报错「Error number: 2003; Symbol: CR_CONN_HOST_ERROR; Message: Can't connect to MySQL server on '%s:%u' (%d)」。当用户贴出包含这条报错的输出、或问这条报错怎么解决时使用。只读排查优先,不需要也不收集数据库密码。

MySQL 错误 2003:TCP 连接没建起来,先看括号里的系统错误号

原文与完整版:https://surinch.com/tools/mysql-error/2003(最后核对 2026-10-30)

一句话结论

ERROR 2003 (HY000): Can't connect to MySQL server on 'host:port' (N) 是客户端库报的错:TCP 连接没有建立,mysqld 还没看到这次请求,所以和密码、权限、max_connections 都无关。最有用的是末尾括号里的数字 N——它是操作系统返回的错误号,Linux 上 111 是端口拒绝、110 是超时、113 是没有路由,先按它分流。

官方报错原文

Error number: 2003; Symbol: CR_CONN_HOST_ERROR; Message: Can't connect to MySQL server on '%s:%u' (%d)

官方 B.3.2.2 节:(2003) Can't connect to MySQL server on 'server' (10061) 表示网络连接被拒绝;应检查服务器上是否有 MySQL 在运行、是否开启了网络连接、你指定的端口是否就是服务器配置的端口。

关键事实

项内容
错误号 / 符号2003 / CR_CONN_HOST_ERROR(客户端错误)
SQLSTATE客户端错误一律为 HY000,不能用来区分具体原因
消息里的占位符'%s:%u' 是客户端实际去连的主机和端口,(%d) 是操作系统错误号
服务端会不会有记录连接没建立时 mysqld 看不到这次请求,Aborted_connects 等状态变量不会增加
相邻错误2002 走 Unix socket 连不上;1045 已连上但认证失败;1040 已连上但名额满;2013 连上后中途断开

2003 卡在哪一层:TCP 握手,不是登录

MySQL 客户端连接分两步:先建立网络连接(TCP/IP,或本机的 Unix socket / Windows 命名管道),再做握手和身份验证。2003 发生在第一步,请求根本没到 mysqld 的认证环节。所以改密码、加 GRANT、调 max_connections 都不会让 2003 消失。

官方把它和 2002 放在同一节(B.3.2.2 Can't connect to [local] MySQL server):2002 是通过 Unix socket 文件连本机失败(不写主机名或写 localhost 时默认走 socket),2003 是通过 TCP/IP 连失败。同一台机器上 -h localhost 报 2002、-h 127.0.0.1 报 2003 是很常见的组合,说明两条路都不通。

括号里的数字怎么读:111、110、113、10061、10060

消息模板是 Can't connect to MySQL server on '%s:%u' (%d),最后的 %d 是连接失败时操作系统给出的错误号。Linux 上的数值来自 asm-generic/errno.h,Windows 上来自 Winsock 错误码。

括号里的数字系统含义通常说明先查什么
111(Linux)ECONNREFUSED:连接被拒绝目标主机在线,但这个端口没有进程监听,或被主机防火墙以 reject 方式拒绝mysqld 是否在跑;port 是否就是你连的端口;bind_address / skip_networking
110(Linux)ETIMEDOUT:连接超时SYN 发出去没有回应,常见于安全组、云防火墙 drop 包,或地址写错到了不存在的机器安全组 / 防火墙入方向规则;IP 是否写对;中间网络
113(Linux)EHOSTUNREACH:没有到主机的路由路由或 ARP 层就不通,或者被 ICMP host-unreachable 拒绝网段、路由、VPN/专线;目标机是否开机
10061(Windows)WSAECONNREFUSED同 111,官方文档原文举的就是这个例子同 111
10060(Windows)WSAETIMEDOUT同 110同 110

111 和 110 的区别最值钱:111 说明网络是通的、包到了对方主机,问题在 MySQL 自己(没起、端口不对、只监听 127.0.0.1);110 说明包在路上被丢了,先找网络和安全组,别急着登服务器翻 my.cnf。

服务器这边:mysqld 在不在、听在哪、有没有关网络

官方建议先确认服务器上有没有名为 mysqld 的进程,再确认它没有被配置成忽略网络连接、也没有只监听本地回环。启动时开了 skip_networking 就完全不接受 TCP/IP 连接;bind_address 设成 127.0.0.1 时只接受本机连接,远程一律 2003。

ps -ef | grep [m]ysqld
ss -ltnp | grep -E 'mysqld|:3306'
mysql -h 127.0.0.1 -P 3306 -u <账号> -p -e "SHOW VARIABLES WHERE Variable_name IN ('port','bind_address','skip_networking','socket');"

ss 输出里如果是 127.0.0.1:3306,远程客户端必然报 2003(Linux 上通常是 111);如果是 0.0.0.0:3306 或 *:3306 而远程仍然 110 超时,问题多半在防火墙或安全组。

客户端这边:确认你连的真是那个地址和端口

  1. 看报错里的 'host:port':它是客户端实际去连的地址。连接串、环境变量、配置中心改了没生效时,这里会露馅。
  2. 从客户端所在机器测端口:nc -vz <host> 3306 或官方举例的 telnet <host> 3306。能连上会收到包含版本号的握手数据;Connection refused 对应 111,长时间无响应对应 110。
  3. 容器 / K8s 里:localhost 指的是容器自己,不是宿主机或另一个 Pod;连 Service 名或宿主机地址。
  4. 域名:先 getent hosts <域名> 看解析到哪个 IP,主从切换后 DNS 缓存没更新也会连到旧地址。

和 2002、1045、1040、2013 怎么分

错误在哪一步失败一句话区分
2002 CR_CONNECTION_ERROR本机 Unix socket 连接socket 文件不存在、路径不一致或没权限;改用 -h 127.0.0.1 走 TCP 可以验证
2003 CR_CONN_HOST_ERRORTCP 连接mysqld 没收到请求;看括号里的系统错误号
1045 ER_ACCESS_DENIED_ERROR已连上,认证失败服务端返回的错误,说明网络是通的
1040 ER_CON_COUNT_ERROR已连上,名额满服务端返回的错误,看 max_connections
2013 CR_SERVER_LOST连上之后查询或握手过程中连接断开

常见问题

mysql 2003 Can't connect to MySQL server 是什么原因?

客户端没能和 mysqld 建立 TCP 连接,请求还没到认证环节。官方给出的检查顺序是:服务器上 mysqld 是否在运行、是否开启了网络连接(skip_networking、bind_address)、端口是否一致、防火墙是否放行。

2003 后面括号里的 111、110、10061 是什么意思?

是操作系统返回的错误号。Linux 上 111 是连接被拒绝(端口没人监听),110 是连接超时(包被丢弃,常见于安全组或防火墙),113 是没有路由;Windows 上 10061 对应拒绝,10060 对应超时。

本机能连,远程连 MySQL 报 2003 怎么办?

先看 bind_address 是否为 127.0.0.1、skip_networking 是否开启,再看服务器防火墙和云安全组是否放行 3306。服务器上用 ss -ltnp 看 mysqld 监听的是 127.0.0.1 还是 0.0.0.0。

2003 和 1045 有什么区别?

2003 是网络层没连上,mysqld 没看到请求;1045 是已经连上、身份验证没通过,属于服务端错误。出现 1045 说明网络是通的。

改了密码或加了授权还是报 2003?

2003 和账号权限无关,改密码和 GRANT 都不会影响它。先按括号里的系统错误号查服务、端口和网络。

给 agent 的使用守则

  • 先让用户贴出完整报错和执行的命令,按上面的顺序做只读检查,再给修改建议。
  • 不要求用户提供密码、连接串里的凭证或生产数据;需要时让用户自己在本机执行命令并贴结果(可先打码)。
  • 改配置(pg_hba.conf、my.cnf、授权语句)前先说明影响并让用户确认;本 skill 不承诺任何修复效果。

来源

完整图文版和相关报错:https://surinch.com/tools/mysql-error/2003

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall