ValueError: the real cause

问题场景

用户使用 accelerate 的 simple_launcher 路径启动训练脚本，例如通过 launch_command / launch_command_parser 以 --cpu --num_processes 1 运行，或经由 TRL CLI 的 trl sft 间接走到该路径。当被启动的子脚本抛出异常并以非零码退出时，父进程只收到一个仅包含返回码和命令行的 CalledProcessError。

该问题对以编程方式处理异常的调用方影响明显：TRL CLI 测试会按异常类型和消息匹配已知的临时性基础设施故障（如并行测试 worker 导致的 GPU 显存压力）并重试，但由于根因没有进到异常对象里，重试逻辑无法命中，临时性故障会被当成真实回归而永久失败。子进程 traceback 确实打印到了终端，但被大量其他 worker 输出淹没，程序化调用方无法利用。

报错原文

Traceback (most recent call last):
  File "boom.py", line 1, in <module>
    raise ValueError("the real cause")
ValueError: the real cause

parent sees : CalledProcessError: Command '['.../bin/python', 'boom.py']' returned non-zero exit status 1.
e.stderr    : None
e.output    : None

原因分析

在 simple_launcher 中，训练脚本通过 subprocess.Popen 启动；当子进程以非零码退出时，父进程基于返回码和命令构造 CalledProcessError，但既没有读出子进程的 stderr，也没有把 output 或 stderr 传给异常对象。子进程 stderr 采用继承方式直接输出到终端，没有被父进程收集，因此异常中这两项均为 None。

作为对比，多进程路径 multi_gpu_launcher 委托给 torch.distributed.run，由 torch elastic 通过 error 文件把子进程的根异常传递回父进程，父进程抛出的 ChildFailedError 会带 “Root Cause” 段落的子进程 traceback。Issue 认为 simple_launcher 同样是 nanny 进程，应提供同等保证。

环境排查

• 确认 accelerate 版本：问题在 1.12.0 上存在，且在 main b795b4838eb33bde60eb398649c4ab006874e3e9 上未变。
• 确认走的是哪条启动路径：--cpu --num_processes 1 或 TRL CLI 会走 simple_launcher；多卡路径走 multi_gpu_launcher（该路径已有根因传播）。
• 确认是否捕获 CalledProcessError 后检查 e.stderr / e.output，以及它们是否为 None。
• Issue 未提供操作系统、Python、PyTorch、CUDA、显卡等版本信息，这些项目无法据此判断。

解决步骤

1. 先本地复现：准备一个只包含 raise ValueError("the real cause") 的 boom.py，用 --cpu --num_processes 1 启动，捕获 subprocess.CalledProcessError 并打印 e.stderr 与 e.output，确认二者为 None。
2. 若需立即拿到根因，可优先尝试应用 PR #4292 的改动：在 simple_launcher 中用 communicate() 收集子进程的 stdout/stderr，并在构造 CalledProcessError 时把捕获内容作为 stderr= 传入，使调用方能在异常对象中看到子进程真实报错。
3. 实现时不要采用“先 wait() 再 read()”的方式。评论中已确认：当子进程在抛错前大量写 stdout 时，该写法会永久挂起；改用 communicate() 后在同一复现场景下 41ms 即完成并带回完整 traceback。建议在该行加注释说明为何不能简化为 wait-then-read。
4. 另一条更彻底但工作量更大的路线是方案 2：把启动脚本接入 elastic 的 error-file 机制，让 simple_launcher 像 multi_gpu_launcher 一样报告失败。Issue 作者表示愿意为任一方案开 PR，但最终选择是方案 1（PR #4292）。
5. 升级或打补丁后重跑上面的复现脚本，观察异常对象中是否携带子进程 traceback。

验证方法

再次用 --cpu --num_processes 1 启动会抛异常的 boom.py，捕获 CalledProcessError 后检查 e.stderr / e.output：若其中包含 ValueError: the real cause 及对应 traceback，说明根因已能传播给程序化调用方，问题解决。同时确认在子进程大量输出 stdout 后报错的场景下，父进程能正常返回而非挂起。

参考来源

huggingface/accelerate #4277