错误库总览
这里收录 ConnProof 的全部稳定错误码。每个错误码对应一篇结论前置的排查文档：开头直接给出一句话结论、最可能原因和第一项操作，正文按平台展开具体步骤。错误码一经发布永不变更，可以放心引用到工单和笔记里。
找文档的三种方式：
- 搜索：按
Ctrl K打开搜索，粘贴原始报错原文或错误码； - 按分类浏览：下面的列表按十大分类组织，也可以用左侧侧边栏；
- 运行诊断：不确定是哪条错误时，安装 ConnProof CLI 运行检测，报告会直接给出错误码和文档链接。
DNS 解析
DNS-001DNS lookup failed域名解析失败时按 域名本身、DNS 服务器、本地缓存与 hosts、网络拦截 四个层面排查，说明如何用 A/AAAA 与系统 lookup 的差异证据定位原因。查看解法 →DNS-002getaddrinfo ENOTFOUNDgetaddrinfo ENOTFOUND 表示操作系统层的地址查询没有返回记录。区分域名真的不存在、hosts 残留、离线环境三种情形的证据判读。查看解法 →DNS-003IPv6 resolved but unreachable域名有 AAAA 记录且解析成功，但本机经 IPv6 无法真正连通目标。判断本地 IPv6 出口质量、系统地址族偏好与应用回退行为。查看解法 →DNS-004DNS resolved to a reserved address公网域名解析出 0.0.0.0、127.0.0.1 或内网地址时，说明解析结果被改写过。区分 hosts 残留、拦截软件、DNS 黑洞与企业分离解析四种成因。查看解法 →
TCP 连接
TCP-001dial tcp: i/o timeoutTCP 连接超时意味着连接请求石沉大海。区分防火墙静默丢弃、主机离线、链路中断三种原因，并说明超时与拒绝的证据差异。查看解法 →TCP-002connect ECONNREFUSEDECONNREFUSED 表示主机可达但端口上没有服务监听。区分服务未启动、端口错位、REJECT 防火墙三种情形与超时的本质差别。查看解法 →TCP-003connection reset by peer解释 RST 重置与正常关闭的区别，重置发生在建连后、传输中、空闲后三种时机各自指向什么原因，以及如何用 ConnProof 观察重置时机。查看解法 →TCP-004network is unreachablenetwork is unreachable 说明本机路由表里没有到达目标的路径，数据包根本没发出去。检查默认路由、IPv6 路由缺失和 VPN 残留路由的具体方法。查看解法 →TCP-005connection closed immediately after acceptTCP 握手成功但对端随即以正常流程关闭连接。区分它与连接被拒绝、被重置的差别，以及负载均衡无健康后端、服务启动中、连接数上限三种典型成因。查看解法 →
TLS 与证书
TLS-001certificate verify failed证书校验失败可能是系统时间错误，也可能是网络中有设备替换了证书。强调不要用忽略证书的方式绕过，并给出安全的证据收集方法。查看解法 →TLS-002TLS handshake timeout解释 TLS 握手超时发生在哪一层，如何通过 DNS、TCP、TLS 证据区分本地网络、代理线路和目标服务器问题。查看解法 →TLS-003unexpected EOF during TLS handshakeTLS 握手进行到一半对端直接关闭连接。区分中间设备识别 ClientHello 后切断、端口跑的不是 TLS 服务、SNI 不被接受三种情形。查看解法 →TLS-004hostname does not match certificate证书有效但保护的域名列表里没有你访问的主机名。区分 IP 直连、SNI 配置错误、CDN 回源错位与中间人替换。查看解法 →TLS-005unsupported protocol / wrong version number握手在版本协商阶段就失败，说明双方没有共同支持的 TLS 版本。区分服务端过旧、客户端过旧、端口跑的不是 TLS 三种成因，以及为什么不该降级迁就。查看解法 →
HTTP 响应
HTTP-001403 Forbidden403 表示请求到达了服务器但被策略拒绝。区分地区/IP 限制、WAF 拦截、凭据失效与请求头校验四类原因及对应证据。查看解法 →HTTP-002429 Too Many Requests429 表示请求频率超过服务端限制。解释限流的常见维度（IP、账号、全局）、Retry-After 的用法，以及为什么重试风暴会让事情更糟。查看解法 →HTTP-003upstream returned 5xx500、502、503、504 各自的含义与责任边界。解释为什么 5xx 基本是服务端问题、用户侧值得做的三件事，以及维护者的排查入口。查看解法 →HTTP-004too many redirects请求在限定次数内没有到达最终页面。用完整重定向链定位循环的两端，区分 HTTPS 与 www 规则互踢、代理与源站方向相反、登录态判断异常三种成因。查看解法 →
WebSocket
WS-001WebSocket upgrade failed解释 WebSocket Upgrade 失败时服务端返回了什么、为什么 CDN 和反向代理是最常见的故障点，以及如何用升级状态码证据定位配置错误。查看解法 →WS-002WebSocket closed immediatelyWebSocket 升级握手成功但连接随即被关闭。用 close code 证据区分服务端鉴权失败、中间设备的数据阶段切断和资源耗尽。查看解法 →WS-003WebSocket connection resetWebSocket 连接没有走正常关闭流程而是被 RST 切断。用保持时长的规律性区分 NAT 超时、流量特征识别与服务端崩溃。查看解法 →WS-004WebSocket upgrade returned 200 instead of 101升级请求收到 200 而不是 101，说明某一层反向代理或 CDN 把它当成了普通 HTTP 请求。解释逐跳头的机制、逐层定位方法与代理配置要点。查看解法 →
订阅连接
SUB-001subscription update failed把笼统的订阅更新失败拆成 URL、DNS、TLS、HTTP、内容五层，按顺序检查每一层的证据，判断是地址过期、网络拦截还是服务端故障。查看解法 →SUB-002subscription response is empty订阅请求成功但响应体为空。区分账号到期、流量用尽、参数缺失和服务端生成故障，说明为什么空响应比报错更难排查。查看解法 →SUB-003subscription URL returned HTML订阅地址返回的是 HTML 网页而不是订阅数据。区分强制门户、地址失效跳转、域名劫持和地址抄写不完整四种原因及其证据。查看解法 →SUB-004subscription URL redirected to login订阅请求被重定向到登录页面，服务端认为当前凭据无效。区分服务方登录页与本地网络门户页，以及订阅地址重置的处理流程。查看解法 →SUB-005subscription URL not found (404)订阅地址返回 404 说明这个路径不存在，与凭据失效的 401/403 是两回事。区分复制截断、路径变更与系统迁移三种成因及各自的处理方式。查看解法 →
代理环境
PROXY-001proxy connection refused应用连接本地代理端口被拒绝：区分客户端没运行、端口不一致、端口被占用三种情形，并用端口监听证据快速定位。查看解法 →PROXY-002system proxy residue detected代理客户端退出后系统代理仍指向已停止的端口，导致全系统断网。分 Windows、macOS、Linux 说明如何确认残留并安全恢复直连。查看解法 →PROXY-003proxy port is not listening预期的代理端口上没有任何进程监听，依赖它的应用全部失败。区分核心启动失败、界面与核心脱节、安全软件拦截与绑定地址错位。查看解法 →PROXY-004proxy environment variables disagree with system proxy环境代理变量与系统代理指向不同端口时，读取二者的应用会走上不同路径，造成'有的能用有的不能'。解释两套机制的分工与统一方法。查看解法 →
长连接
LONG-001stream disconnected before completion解释 stream disconnected before completion 出现的位置，如何用连接保持时长证据区分 NAT 超时、线路策略和服务端回收，并给出分平台的排查步骤。查看解法 →LONG-002long connection closed before completion长连接被对端以正常流程关闭，但时间点早于业务预期。用存活时长的统计规律区分服务端回收、中转时长上限和心跳失配。查看解法 →LONG-003idle connection timeout连接因长时间无数据往来被关闭。解释 NAT 表、服务端 idle timeout 与移动网络省电策略如何叠加，以及心跳与重连的取舍。查看解法 →
客户端行为
CLIENT-001client connected but no internet客户端显示已连接但网页打不开：拆解连接状态与实际可用性的差别，用 DNS 与出口证据区分节点出口故障、DNS 配置和分流规则问题。查看解法 →CLIENT-002all nodes timeout当客户端里所有节点同时超时，问题几乎不在节点。按系统时间、基础网络、防火墙、订阅时效四步在十分钟内定位本地原因。查看解法 →CLIENT-003browser works but application fails浏览器访问正常而某个应用无法联网，差异几乎都在代理生效范围：应用不读系统代理、分流规则漏掉目标、应用内置代理配置过期。查看解法 →