dbt docs generate执行报错：SSLError(bad handshake: SysCallError(-1, 'Unexpected EOF'))

安全阿岳

2026-7-15

解决方案

检查并更新本地SSL根证书
Windows系统的SSL根证书可能存在损坏或未更新的情况，导致长时间连接后握手失败。执行以下命令更新：
```
# 生成最新根证书文件
certutil -generateSSTFromWU roots.sst
# 将证书导入本地根证书存储
certutil -addstore -f root roots.sst
```
操作完成后重启终端，重新执行dbt docs generate。
调整dbt与Snowflake的超时配置
长时间运行的dbt docs generate可能因超时触发连接中断，在配置文件中延长超时参数：
1. 在dbt_project.yml中添加全局网络配置：
```
config:
  network_timeout: 600  # 单位：秒
  retries: 5
```
1. 在profiles.yml的Snowflake输出配置中细化连接超时：
```
your_profile_name:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: your_account_id
      # 其他已有配置...
      connect_timeout: 600
      socket_timeout: 600
```
临时禁用Windows Defender实时保护
Windows Defender的网络监控可能干扰SSL握手流程，临时关闭实时保护（测试完成后务必重新开启），再执行命令验证是否解决问题。
重新安装指定版本的依赖包
即使版本与团队一致，本地依赖文件可能存在损坏。先卸载现有包：
```
pip uninstall -y dbt-snowflake snowflake-connector-python
```
再重新安装指定版本：
```
pip install dbt-snowflake==1.5.3 snowflake-connector-python==1.5.2
```
建议在独立的Python虚拟环境中执行，避免依赖冲突。
排查本地网络稳定性
尝试切换网络（如手机热点），排除本地路由器或网络链路不稳定导致的连接中断。部分老旧网络设备对长连接的维持能力有限，可能引发意外EOF错误。