R包gage、clusterProfiler连接KEGG服务器下载参考数据报错

两个此前运行正常的KEGG通路富集相关R包（gage、clusterProfiler）同时触发网络类报错，核心错误均为Failure when receiving data from the peer，不属于单个包的代码逻辑问题，可按以下步骤排查修复。

报错场景复现 #

gage包报错 #

调用kegg.gsets()下载KO通路参考数据时触发curl连接错误：

library(gage)
kg.ko = kegg.gsets("ko") # 加载KEGG直系同源通路数据集
# 报错输出
Error in curl::curl_fetch_memory(url, handle = handle) : 
  Failure when receiving data from the peer

clusterProfiler包报错 #

调用enrichKEGG()做KO富集分析时，函数内部自动拉取KEGG注释数据失败：

library(clusterProfiler)
# 待富集的KO号示例
de_kegg_chr <- c("K14847", "K19009", "K00078", "K21407", "K23285", "K06972")
enrich <- enrichKEGG(gene = de_kegg_chr,
                     organism = "ko",
                     keyType='kegg',
                     pvalueCutoff = 0.01)
# 报错输出
Reading KEGG annotation online:

fail to download KEGG data...
Error in download.KEGG.Path(species) : 
  'species' should be one of organisms listed in 'http://www.genome.jp/kegg/catalog/org_list.html'...
In addition: Warning message:
In utils::download.file(url, quiet = TRUE, method = method, ...) :
  URL 'https://rest.kegg.jp/link/ko/pathway': status was 'Failure when receiving data from the peer'

排查步骤（按优先级排序） #

• 先验证KEGG服务可用性：在本地浏览器直接访问报错中提示的KEGG接口地址，若能正常加载内容，排除服务器端故障，问题定位在R环境网络配置
• 检查R默认下载方法：在控制台运行getOption("download.file.method")查看默认下载工具，若默认调用系统curl/wget，大概率是本地工具版本过旧、被安全软件拦截导致传输中断
• 检查R环境代理配置：运行Sys.getenv(c("http_proxy","https_proxy"))，查看是否存在失效代理、端口配置错误的问题——系统代理更新后R环境不会自动同步，是这类问题的高发原因
• 检查SSL证书配置：本地系统证书库过期、curl包证书路径配置错误，会导致HTTPS连接建立后校验失败，中途断开数据传输

可直接落地的解决方案 #

1. 临时调整R下载参数绕开curl兼容问题
   在运行富集分析代码前，先执行以下配置，切换下载方法为libcurl，必要时临时关闭SSL强校验（仅用于可信网络环境下的临时分析）：

# 切换默认下载方法
options(download.file.method = "libcurl")
options(url.method = "libcurl")
# 若存在证书校验报错再执行下面这行
httr::set_config(httr::config(ssl_verifypeer = FALSE))

2. 修正R环境代理配置
   如果本地需要通过代理访问外网，手动配置正确的代理地址和端口（替换为本地实际代理端口，常见端口为7890、1080等）：

Sys.setenv(http_proxy = "http://127.0.0.1:替换为你的代理端口")
Sys.setenv(https_proxy = "http://127.0.0.1:替换为你的代理端口")

如果不需要代理，直接清空环境变量中的代理配置即可：

Sys.unsetenv("http_proxy")
Sys.unsetenv("https_proxy")

3. 绕开clusterProfiler内置在线下载逻辑
   如果调整网络配置后仍无法正常拉取数据，可手动下载KEGG KO通路注释数据，整理为两列格式（第一列为通路ID，第二列为对应KO号），传入通用富集函数enricher()做分析，完全跳过内置下载步骤，得到的富集结果和enrichKEGG()完全一致。
4. 回滚兼容异常的依赖包
   如果近期更新过curl包或R主程序，可尝试将curl包回滚到之前的稳定版本，部分新版本curl包和系统网络组件存在兼容问题，也会触发数据接收失败的报错。

内容的提问来源于stack exchange，提问作者Alex