一颗孤寂的树第一次接触WandB的时候，我一度觉得它才是整个训练流程里最难伺候的环节。模型还没开始收敛，WandB先抛一个Not logged in；等你登录完了，训练跑了六个小时，它又跳出一串ConnectionError，所有指标全都停在本地没同步。这种报错本身不算复杂，但因为它总出现在训练已经开始之后，排查时间全都被浪费在等待重跑上。
这篇文章是我拿WandB当主力实验跟踪工具这两年沉淀下来的排错笔记，把高频报错按训练流程的生命周期归类：登录认证、脚本API调用、结果同步、分布式训练、版本环境冲突。每个环节我都会先讲报错背后的机制，再给可以直接照做的排查步骤。无论你是刚把wandb加进训练脚本的研究生，还是在集群上维护多卡训练任务的工程师，这套方法应该都能帮你省下不少冤枉时间。
1. 登录认证阶段的报错：API Key失效远比你想的更频繁
1.1 "Not logged in"到底丢的是什么
先看最常见的一种：在服务器上跑训练，代码执行到wandb.init()附近，日志里突然出现wandb: Not logged in，然后弹出一个登录链接。问题是服务器根本没有浏览器，你复制链接到本地登录，再回到终端时可能已经超时了。
这个报错的本质是客户端找不到合法的认证凭据。WandB客户端默认会把登录凭据写进用户目录下的.netrc文件，同时把一些本地配置放在~/.config/wandb。只要你换了登录用户、重建了容器、或者home目录被清理过，这些文件就没了，Not logged in自然出现。
排查方式很简单，先确认当前登录状态：
bash复制wandb login --verify
cat ~/.netrc | grep -i machine
ls -la ~/.config/wandb/
--verify会直接告诉你是不是已经登录；~/.netrc里能看到w&b的认证条目；~/.config/wandb目录是否存在则能判断配置是否完整。实测下来，这三条命令能在30秒内定位90%的登录类问题。
1.2 用环境变量注入API Key，而不是依赖交互式登录
既然交互式登录在服务器场景下很难用，最稳妥的办法是把API Key直接作为环境变量注入。WandB客户端初始化时能找到WANDB_API_KEY，就跳过交互式登录流程。
bash复制export WANDB_API_KEY=你的key
这里有个细节容易踩坑：如果你的key里包含特殊字符，某些shell会把空格或符号截断，所以建议在.bashrc或提交脚本里用单引号包裹：
bash复制export WANDB_API_KEY='你的key'
另外，WANDB_API_KEY的优先级高于.netrc文件。如果你之前登录过，后来又手动改过key，以环境变量为准。这一点在多人共用的GPU服务器上特别重要——别人登录过的凭据不影响你的训练，你也不会误用自己的key污染别人的实验。
提示：在CI流水线或集群调度任务里，直接把key写进代码或SQLite文件里是个坏习惯。正确做法是放环境变量或密钥管理系统，这样即使日志输出也不会泄露完整凭据。
1.3 无外网环境与自建服务场景下的认证问题
如果你的训练集群无法直接访问云端服务端，或者你们团队用的是私有化部署的W&B服务，那报错会变成AuthenticationError或Failed to authenticate。这两个报错比Not logged in更有迷惑性，因为它可能不是key的问题，而是客户端连错了服务器。
排查时先确认客户端实际访问的服务地址：
bash复制wandb status
如果输出里显示的是https://api.wandb.ai而你其实应该访问团队自建服务，就需要设置：
bash复制export WANDB_BASE_URL=http://你的服务地址:8090
自建服务场景下，WANDB_BASE_URL和WANDB_API_KEY必须是一对匹配的凭据。很多人只改了base_url，key还是云端账号的，结果报了AuthenticationError，很容易误判。
我把认证阶段常见的状态整理成一个表，方便对照：
| 报错关键词 | 实际含义 | 处理方式 |
|---|