常见报错与错误码速查：从限流到锁库的对照表
OpenList 的报错信息大多直接可读，这里把官方文档与社区高频的报错按「现象 - 原因 - 对策」整理成速查表。
网盘与驱动类
| 报错 | 原因与对策 |
|---|
| TooManyRequests / Too Many Requests（阿里云盘 Open） | 开放平台限流：拉长缓存、减少刷新、错峰使用，详见 阿里云盘 |
| ExceedCapacityForbidden（阿里云盘 Open） | 容量限制类，见驱动文档其他说明一节 |
| failed to refresh token: refresh_token is missing | 添加驱动时令牌填错或没填，重新授权获取 |
| ForbiddenDriveNotValid | 驱动已弃用：典型如老「阿里云盘」驱动，换用阿里云盘 Open |
| hit black userlist（百度） | 平台风控临时拦截，一般等 24 小时自行恢复 |
| 123 云盘 json 反序列化报错 | 搭建设备被平台临时拉黑，停几小时到一天再挂 |
存储配置类
| 报错 | 原因与对策 |
|---|
| UNIQUE constraint failed: x_storages.mount_path | 挂载路径重复：每个路径全站唯一，聚合需求用 别名 |
| Field validation for 'MountPath' failed | 挂载路径留空：必填，挂根目录填 / |
网络类
| 报错 | 原因与对策 |
|---|
| no such host / dns lookup failed / connection refused | 机器到网盘接口的网络不通，自查 DNS 与出网 |
| TLS handshake timeout | 常见于海外 VPS + IPv6 访问阿里接口：改 hosts 或关 IPv6（官方 FAQ 有具体地址） |
| 挂 Terabox 列表为空 | Terabox 限制非海外 IP 访问，国内机器需让流量走代理 |
系统与程序类
| 报错 | 原因与对策 |
|---|
| GLIBC_2.28 not found（Linux） | 系统 glibc 太老：换 musl 静态版本或改用 Docker |
| Token is expired | 登录有效期（默认 48 小时）到了，重新登录；反复出现则查 CDN 缓存（见 登录排查） |
| database is locked | SQLite 建索引期间正常；持续锁库见 搜索索引 |
| System error: n.replaceAll is not a function | 浏览器内核太老，按官方建议在自定义头部补 polyfill |
| Invalid regular expression（油猴） | 浏览器脚本插件与页面冲突，禁用相关脚本 |
通用排查心法
- 先看日志：报错全文在日志里，比弹窗更完整（见 日志与更新）
- 区分「谁的问题」：带网盘名称 / 平台错误码的，多半是平台侧；语法类、权限类的是本站配置
- 等 vs 改：风控类等一等，配置类当场改；反复重试只会加重风控