错误/状态代码

此页面上的所有地址均适用于 libtpu-0.0.40-cp314 轮中附带的 libtpu.so(build-id 89edbbe81c5b328a958fe628a9f2207d)。 Offsets是文件偏移量；对于 .rodata 字符串表，这些等于虚拟地址(1:1 映射 — .rodata 在磁盘和内存中均从 0x84a0000 开始)。其他版本会有所不同。

摘要

libtpu 通过 absl::Status 报告每个故障，而不是通过 errno 或自定义枚举。 Status 要么是 OK，要么携带规范的 absl::StatusCode 值之一 — INVALID_ARGUMENT、INTERNAL、FAILED_PRECONDITION、UNIMPLEMENTED、RESOURCE_EXHAUSTED、 NOT_FOUND、UNAVAILABLE、OUT_OF_RANGE、ABORTED、DEADLINE_EXCEEDED、ALREADY_EXISTS、PERMISSION_DENIED、DATA_LOSS、CANCELLED、 UNKNOWN — 加上消息字符串。在 PJRT 边界，代码被转换为 PJRT_Error_Code(四个 PJRT_Error_* C-API 入口点 — PJRT_Error_Destroy、PJRT_Error_Message、PJRT_Error_GetCode、PJRT_Error_ForEachPayload — 加上 pjrt::PjrtErrorCodeToStatusCode 转换器都存在)，因此 JAX/XLA 客户端看到相同的分类法。本附录是综合的跨系列索引：它按子系统对消息模板进行分组，给出每个系列的代表性逐字字符串及其 .rodata 地址，命名该系列通常携带的 StatusCode，并指向完整编目每个表面的更深层次页面。

TPU 代码可以通过三种习惯用法来构造不正常的 Status，而在调用站点使用的习惯用法可以修复 StatusCode，而单独的格式字符串则不能。按调用点数量计算的主要习惯用法是流构建器 xla::status_macros::MakeErrorStream(RET_CHECK(c) << … / return InvalidArgument(…) << … 宏)。字节确认习惯用法是模板化工厂 xla::<Code>StrCat<Types…>(literal0, arg0, literal1, arg1, …, absl::SourceLocation) — 一个扁平化的 absl::StrCat，其 Itanium 损坏的模板参数包命名每个交错的文字段和类型化参数；一个分解后的示例为 xla::InvalidArgumentStrCat<char const(&)[28], long&, char const(&)[22], std::string>。第三个，很少使用，是散文自由函数 absl::<Code>Error("…")。错误 prose 绝大多数是 %s/%d 格式的(字符串参数是形状、布局、指令名称、设备名称；整数参数是维度、计数、大小)——指针和浮点说明符仅限于低级驱动程序和成本模型路径。

该页面的组织方式如下： StatusCode 关键字表面和主要模板系列的概览表；每个系列一个 TABLE 部分(编译/HLO 验证器、运行时/驱动程序/PJRT、ICI/集体、MSA/内存、SparseCore/嵌入、调度程序)，具有代表性字符串和地址； CHECK/RET_CHECK/致命模板；面向用户的 提示 字符串(附加到错误后的可行补救措施)；以及 Megascale ErrorAggregator 路径(如何收集跨主机故障并将其分类为单个摘要)。这是当你遇到 libtpu 错误时 grep 的附录。

重新实现，合约为：

• absl::Status 模型 — 规范 StatusCode 集 + 消息字符串，在 C-API 边界翻译为 PJRT_Error_Code；没有 errno。
• 三种构造习惯用法，其中一种修复 StatusCode(MakeErrorStream 流、<Code>StrCat 工厂、absl::<Code>Error 散文)。
• 模板系列分类法：哪个子系统引发哪种消息形状，以及每个系列携带的 StatusCode。
• 提示字符串约定：可操作的补救措施(--flag=value、go/<link>、b/<id>、容量建议)连接到错误消息上。
• 超大规模扇入：收集每个主机 MegaScaleRuntimeError 报告，分类为一个 Cause，并作为摘要发出。

状态类型	absl::Status / absl::StatusOr<T>(普遍存在；>2600 个 absl::Status 符号，>11500 个 StatusOr 符号)
面向客户端的代码	PJRT_Error_Code(由pjrt::PjrtErrorCodeToStatusCode翻译自absl::StatusCode；存在PJRT_Error_GetCode / _Message / _Destroy / _ForEachPayload)
主要构造习语	xla::status_macros::MakeErrorStream — RET_CHECK(c) << … / return InvalidArgument(…) << …
字节确认工厂	xla::<Code>StrCat<Types…>(…, absl::SourceLocation) — 38 个 InvalidArgument、31 个未实现、29 个内部、1 个 ResourceExhausted(不同的 C1/C2 角色)
散文工厂	absl::<Code>Error("…")(稀疏)
RET_CHECK 前缀	"TPU_RET_CHECK failure (" @ 0xa183292
检查前缀	"Check failed: '" @ 0xa1a64de，"Check failed: " @ 0xa285fb1
格式成语分割	printf风格的%s/%d/%lu/%f(house风格)占主导地位； Megascale + 集体验证器使用的位置 $0/$1/%v

注意 — 格式字符串不是可靠的 StatusCode 预言机。只有 99 个 <Code>StrCat 工厂实例和 MakeErrorStream 调用点对代码进行字节确认；对于通过 return InvalidArgument(absl::StrFormat(template, …)) 馈送的大型 printf 风格系列，StatusCode 在(仅反汇编)调用站点设置。下面的每个系列 StatusCode 列是该系列的“主导”代码，而不是每个模板映射的字节确认代码。将任何单行的 StatusCode 视为中等置信度，除非该系列完全是工厂构建的。

---

概览：StatusCode 表面和模板系列

StatusCode 关键字出现

字符串表中每个 absl::StatusCode 名称的噪声过滤出现。这是一个频率信号，而不是每个模板的计数 - 它指示二进制文件依赖哪些代码。

状态代码	发生	注释
INVALID_ARGUMENT	~300	验证者/用户输入的代码；最大的工厂系列(38 StrCat)
UNIMPLEMENTED	~169	“不支持”/“未实现”散文(31 StrCat)
NOT_FOUND	~75	查找未命中(驱动程序地图、时间表参考)
FAILED_PRECONDITION	~56	状态/顺序违规(固件队列状态、初始化顺序)
RESOURCE_EXHAUSTED	~21	OOM / 容量(1 StrCat；MSA 主募集者)
UNAVAILABLE	~15	瞬态传输/设备关闭
OUT_OF_RANGE	~14	索引/边界错误
ABORTED	~8	取消/拆解
ALREADY_EXISTS	~3	重复注册
DEADLINE_EXCEEDED	~3	超时路径(GTC、sflag、截止时间计时器)
PERMISSION_DENIED	~2	罕见
DATA_LOSS	~1	罕见
INTERNAL	—(见注释)	29 InternalStrCat + ~13 MakeErrorStream 站点字节确认

GOTCHA — 原始 Internal 关键字计数由 /internal/ 源路径组件主导，该组件烘焙到字符串表中的数千个 .cc 路径中；它不是可用的内部状态计数。可靠的内部数字是 29 个 InternalStrCat 工厂实例加上 MakeErrorStream 站点，而不是关键字计数。

模板系列

计数是每个子系统经过错误散文过滤的候选者(模板可以匹配多个组；第一匹配获胜排序：编译 → MSA → ICI → SparseCore → 运行时 → 调度程序 → 超大规模)。完整提取的表面大约有 2937 个不同的错误/状态模板(2799 个 printf 样式，138 个位置模板)。

家族	~模板	显性状态代码	主导成语
编译/HLO/验证器	~875	INVALID_ARGUMENT	StrFormat %s/%d + RET_CHECK
运行时/驱动程序/PJRT	~177	INTERNAL / FAILED_PRECONDITION	StrFormat %s/%d/%p + errno
ICI/集体	~90	INTERNAL / DEADLINE_EXCEEDED	StrFormat %d/%s + $N (MSC)
MSA /内存/分配	~79	RESOURCE_EXHAUSTED / INTERNAL	StrFormat %zu/%lld
SparseCore / 嵌入	~68	INVALID_ARGUMENT	StrFormat %d/%s/%f
超大规模(DCN 运行时)	~21	INTERNAL / LOG(FATAL)	位置 $0/$1
调度程序/燃料/先进先出	~15	INTERNAL / RET_CHECK	StrFormat %s/%d/%c
CHECK / RET_CHECK / 致命	—	中止(无状态)	绝对 CHECK / LogMessageFatal

---

编译/HLO/验证器系列

单个最大错误块。这些是 JAX/XLA 用户在程序格式错误时看到的形状推断和 HLO 验证器诊断 — 等级/维度/形状不匹配、操作码/操作数计数错误、位广播和布局违规。几乎所有都带有 INVALID_ARGUMENT(验证者的签名)或未通过 RET_CHECK。比对样式"%d vs. %d" / "%s vs. %s"为验证者的指纹；它附加两个不匹配的操作数值。

地址	代表模板	状态代码
0x857d7ed	"A dimension number is out of range in Dot: %s. %s %s"	INVALID_ARGUMENT
0x857d595	"Argument to Cholesky must have rank >= 2; shape was %s"	INVALID_ARGUMENT
0x8580369	"All reduced tensors must have the same dimension. Tensor 0 has shape %s, Tensor %d has shape %s"	INVALID_ARGUMENT
0x8728000	"Binary op expects 2 operands, but got %d"	INVALID_ARGUMENT
0x872a259	"broadcast_dimensions contains invalid value %d for result with rank %d"	INVALID_ARGUMENT
0xa02c26f	"Cannot concatenate arrays that differ in dimensions other than the one being concatenated. Dimension %d in both shapes must be equal (or compatible): %s vs %s."	INVALID_ARGUMENT
0x858400c	"Bad scalar opcode in slot 0, opcode: %d bundle: %v, bits: %s"	INVALID_ARGUMENT
0xa01cdc3	"Bitcast requires a new on-device shape to have the same size of %d bytes, but got %d bytes."	INVALID_ARGUMENT
0x857b3fa	"sharding's tile count and device count does not match: %d vs. %d; shape=%s, sharding=%s"	INVALID_ARGUMENT

QUIRK — "Bad scalar opcode in slot 0, opcode: %d bundle: %v, …" (0x858400c) 中的 %v 说明符不是 C-printf。它是absl AbslStringify扩展； bundle 参数是通过其字符串生成器呈现的每代 gxc::gfc::isa::TensorCoreBundle。匹配工厂经过字节确认：xla::InvalidArgumentStrCat<char const(&)[56], absl::StatusOr<…gxc::gfc::isa::TensorCoreBundle>>，六个 TensorCoreBundle 轴承工厂实例之一(每代 gxc::gfc / gxc::glc / vxc 变体)。将 %v 视为 %s 的拼写错误的重新实现将导致捆绑包格式错误。

---

运行时/驱动程序/PJRT 系列

设备生命周期、驱动程序状态机、固件队列转换、芯片计数和拓扑检查以及 PJRT C-API 表面。混合状态代码：FAILED_PRECONDITION 表示状态/顺序违规，INTERNAL 表示驱动程序不变故障，NOT_FOUND 表示映射未命中。这是最有可能嵌入 %p(指针)和 errno 派生的 %d 的系列。

地址	代表模板	状态代码
0xa077a78	"Cannot transition to %s: the firmware queues are not in %s state; they are in %s state."	FAILED_PRECONDITION
0x96c33b2	"Can't close driver while in state %s; are multiple threads trying to open / close?"	FAILED_PRECONDITION
0xa0430a3	"Cannot remove a driver for %s, was not found in map."	NOT_FOUND
0xa09fdcd	"Chip count (%d) is not supported."	INVALID_ARGUMENT
0xa00ab4b	"Expected %d chips per tray, actually found a tray with %d chips."	INTERNAL
0x858a3de	"failed initializing StreamExecutor for device ordinal %d: %s"	INTERNAL
0xa1a96ba	"executable is built for device %s of type \"%s\"; cannot run it on device %s of type \"%s\""	INVALID_ARGUMENT
0x94b68ce	"Can't get the optimized program for executable \%s`: MPMD execution is not supported by PJRT C API"`	UNIMPLEMENTED
0xa0a9937	"%d DMA buffers were still outstanding when the driver was re-opened. These buffers must be unmapped before the driver can be re-opened."	FAILED_PRECONDITION

---

ICI/集体家族

芯片间互连拓扑、链路运行状况、路由和集体缓冲区验证。携带 INTERNAL(拓扑/路由不变式)、DEADLINE_EXCEEDED(GTC 收敛、sflag 等待)，或显示致命链接标记(请参阅致命部分)。 Megascale 标记的集体缓冲区验证器使用位置 $0/$1 习惯用法而不是 printf。

地址	代表模板	状态代码
0xa0b4247	"Atomic/Special DMA must have length of %d bytes, got %d."	INVALID_ARGUMENT
0xa0b3abc	"Cannot find unicast link next hop routing table for link port %d."	INTERNAL
0xa0d5412	"Detected ICI link failures along %d dimensions, but only 1-dimensional link fault is allowed.."	FAILED_PRECONDITION
0x871106b	"GTC failed to converge (max diff %d > %d) before timeout (%s) expired"	DEADLINE_EXCEEDED
0x8583d20	"ICI Probe failed. local port: %d name: %s took %d us. status: %s"	INTERNAL
0xa0ba533	"ICI routing failed to retrieve %dth hop dimension from bit encoded cache data."	INTERNAL
0x9a573e9	"ALL_REDUCE Output buffer size is not == Input buffer size. Input size: $0 Output size: $1 Group Size $2 Key: $3 Module: $4 MegascaleInfo: $5"	INVALID_ARGUMENT
0x9c142f9	"ALL_GATHER Input buffer size is not (Output buffer size / group size). Input size: $0 …"	INVALID_ARGUMENT

注意 — $0/$1 字符串是 absl::Substitute 位置模板，是二进制文件中的第二个格式化习惯用法。它们聚集在 Megascale 运行时和集体缓冲区大小验证器中。 protobuf 扩展声明验证器也使用 $N，但这是一个静态链接库，而不是 TPU 代码，并且不包括在 TPU 模板计数中。

---

MSA /内存/分配系列

内存空间分配、HBM/VMEM/SMEM/CMEM 分配、预取、碎片整理和寄存器分配器。对于真正的 OOM，主要的 StatusCode 是 RESOURCE_EXHAUSTED(单个 ResourceExhaustedStrCat 工厂位于此处)，对于分配器不变违规，主要的 StatusCode 是 INTERNAL。请注意 %zu/%lld 尺寸说明符。

地址	代表模板	状态代码
0xa030cd9	"AllocateBufferForMemorySpace: Unsupported memory space: %s."	INVALID_ARGUMENT
0x858aa58	"Allocation (size=%lld) would exceed memory (size=%lld) :: %s :: %s"	RESOURCE_EXHAUSTED
0xa1300d0	"Failed to allocate %zu bytes. Memory limit: %zu bytes. Used: %zu bytes.)"	RESOURCE_EXHAUSTED
0xa13e8e5	"Failed to allocate node (%zu bytes). Memory limit: %zu [bytes]. Used: %zu [bytes].)"	RESOURCE_EXHAUSTED
0xa01cf08	"Out of memory allocating %d bytes."	RESOURCE_EXHAUSTED
0xa09a63e	"Number of bytes %lld allocated must be a multiple of chunk size %lld."	INTERNAL
0x857eed1	"Register allocator verification failure: live range %s; instruction %s"	INTERNAL
0xa02b12f	"Scoped allocation with size %s and limit %s exceeded scoped %s limit by %s."	RESOURCE_EXHAUSTED
0x8584ecd	"Error defragmenting HBM %s: %s"	INTERNAL

---

SparseCore /嵌入系列

xla_sc_* / BarnaCore 嵌入引擎：小批量构建、表验证、优化器/功能限制和 32 位 SparseCore 元素限制。主要是面向用户的 INVALID_ARGUMENT 配置错误(操作员可以修复嵌入配置)。

地址	代表模板	状态代码
0xa0a9715	"barna_core_infeed_queue_hbm_address must be %d-byte aligned."	INVALID_ARGUMENT
0xa0d36d1	"Invalid num_features: %d found for table: %s in the TPU embedding configuration. Valid values are >0."	INVALID_ARGUMENT
0xa030dd4	"Could not find valid TPU batch of length at least %d at position %d for row %d. The embedding work in one sample exceeds what the BarnaCore can process: %s. %s."	INVALID_ARGUMENT
0xa0b7076	"Logical replicas must evenly divide the SparseCores in the system. logical_replicas = %d, physical_sparse_cores = %d."	INVALID_ARGUMENT
0xa069f4e	"Number of TPU tables on row: %d exceeds what the BarnaCore hardware supports: %d > %d. This is mostly likely a result of incorrect partitioning."	INVALID_ARGUMENT
0xa0ff40e	"Row pointers would exceed available SCS Smem (%d bytes > %d bytes)"	RESOURCE_EXHAUSTED
0xa07d172	"Scatter operand has %d elements, which exceeds the 32-bit limit. Unsupported on SparseCore."	UNIMPLEMENTED
0x86fa1ad	"Failed to parse TPU embedding partitioner optimization objective \"%s\". Valid options: performance, hbm_usage, hybrid"	INVALID_ARGUMENT

---

调度程序/燃料/FIFO 系列

延迟隐藏调度程序、注释解析器、优化“燃料”预算和 FIFO 推送/弹出验证。小家庭；主要包含INTERNAL / RET_CHECK，INVALID_ARGUMENT用于面向用户的--xla_fuel标志值错误。

地址	代表模板	状态代码
0x857fa91	"async-done for %s must be scheduled before %s"	INTERNAL
0x858a9b8	"Cannot schedule FIFO pop instruction when the FIFO is empty %s :: %s"	INTERNAL
0x857ad7e	"Cannot schedule FIFO push instruction when the FIFO is full. FIFO name: %s. (element count %d vs %d). %s :: %s%s"	INTERNAL
0xa086733	"Reference instruction %s was not found in the schedule."	NOT_FOUND
0xa03ca6a	"Illegal value for --xla_fuel. Saw %s, but expected token %s to be an integer."	INVALID_ARGUMENT
0x862868f	"GVN: Not replacing %s because GVN is out of fuel"	(日志/无状态)

---

CHECK / RET_CHECK / 致命模板

这些是中止路径 - 它们不返回 Status，它们终止。 absl CHECK 系列将源表达式 字符串化为rodata(大块文字 C++ 源代码出现在字符串表中，这是 CHECK(expr) << "msg" 的副作用)；这些源片段是 CHECK 条件证据，而不是消息模板。正确的运行时检查模板是下面的裸absl 前缀。

地址	模板	起源/宏
0xa1a64de	"Check failed: '"	absl CHECK / QCHECK 运行时前缀
0xa285fb1	"Check failed: "	absl CHECK 运行时前缀(无引号)
0xa183292	"TPU_RET_CHECK failure ("	XLA TPU RET_CHECK 宏
0xa2300c5	"MakeErrorStream destructed without getting absl::Status: "	status_macros 自检
0xa1e7cb3	"!!!! FATAL ERROR !!!! for "	ICI致命错误检查
0xa046045	"Fatal error occurred. Data links will go down."	ICI 硬故障标记
0xa1b3810	"FATAL ERROR RECEIVED FROM HARDWARE!!!"	硬件致命中断
0xbe7d460	"FATAL ERROR: This binary was compiled with aes enabled, but this feature is not available on this processor (go/sigill-fail-fast).\n"	Absl CPU 功能启动保护
0xa045d37	"Aborting the coordinator after collecting errors from all workers as megascale_error_reporter_abort_on_hang is set to true. …"	超大规模 LOG(FATAL)

QUIRK — go/sigill-fail-fast 致命错误不是 TPU 路径。它是静态链接的absl CPU功能启动防护，构建所需的每个ISA功能的一个变体：aes、avx、mmx、pclmul、popcnt、sse、sse2、 sse3、sse4.1、sse4.2、ssse3、cmpxchg16b(共12个)。如果主机 CPU 缺乏该功能，它会在任何 TPU 代码运行之前触发。 12 个变体字符串是从 0xbe7d460 开始的连续运行。 TPU 表面的重新实现不需要复制它；操作员发现它存在主机 CPU 问题，而不是 TPU 问题。

MakeErrorStream 自检字符串("MakeErrorStream destructed without getting absl::Status:"、"…shift called after getting absl::Status:"、"…got absl::Status more than once:")是状态宏机制发出的有关其自身误用的诊断，而不是有关正在编译的程序的诊断。

---

状态-构造成语

相同的消息文本可以携带不同的 StatusCodes，具体取决于 Status 的构建方式。存在三种习语；仅前两个字节确认代码。

1. xla::status_macros::MakeErrorStream  — the dominant idiom by callsite
     RET_CHECK(cond) << "message"        →  INTERNAL (RET_CHECK) or the
     return InvalidArgument(...) << ...      explicitly-named code
   Each StatusOr<T> return type the macro is used in emits a
   MakeErrorStreamWithOutput<T> conversion operator (the operator<<
   and the cv-StatusOr<T> conversion are visible per T in the symtab).

2. xla::<Code>StrCat<Types...>(lit0, arg0, lit1, arg1, ..., SourceLocation)
     A flattened absl::StrCat. The mangled type pack names every piece.
     Distinct C1/C2 ctor instantiations:
       InvalidArgumentStrCat    38   →  INVALID_ARGUMENT
       UnimplementedStrCat      31   →  UNIMPLEMENTED
       InternalStrCat           29   →  INTERNAL
       ResourceExhaustedStrCat   1   →  RESOURCE_EXHAUSTED
     Example (demangled):
       xla::InvalidArgumentStrCat<char const(&)[28], long&,
                                  char const(&)[22], std::string>
       = InvalidArgument("<27-char lit>", long, "<21-char lit>", string)

3. absl::<Code>Error("...")  — prose free function, used sparingly
     e.g. return absl::InternalError("Invalid error type")
```text

> **注意 —** `<Code>StrCat` 参数类型无需反汇编即可恢复，因为 Itanium 修饰对它们进行编码：`RA<N>_Kc` 是 `const char(&)[N]` 文字段(可见文字 = N−1 个字符)， `m`/`l`/`i`/`f` 按值计算为 `unsigned long`/`long`/`int`/`float`，而 `NSt…basic_string…` 为`std::string`。在 99 个工厂中，参数绝大多数都是字符串 + `long`； `float` (2) 和 `TpuVersion` (1) 很少见。这是二进制文件中 format-arg C++ 类型可字节恢复的唯一位置。

### 解析模板的StatusCode

要从 grep 错误字符串转到其 StatusCode，请确定哪个习惯用法构建了它。页表给出了“家族主导”代码；每个调用点的真相是以下三种模式之一：

```c
// Pattern A — factory (byte-confirmed). The string is split into literal
// segments interleaved with typed args; the <Code> in the symbol name IS
// the StatusCode. Grep the demangled symtab for the literal-segment text.
//   return InvalidArgumentStrCat("Chip count (", count, ") is not supported.");
//   → symbol xla::InvalidArgumentStrCat<char const(&)[N], int, char const(&)[M]>
//   → INVALID_ARGUMENT, certain.

// Pattern B — RET_CHECK / streaming. The macro wraps a fixed code; the
// streamed text is appended. The "TPU_RET_CHECK failure (" prefix at the
// front of the rendered message is the tell.
//   TPU_RET_CHECK(operands.size() == 2) << "got " << operands.size();
//   → INTERNAL (RET_CHECK is always INTERNAL), certain by prefix.

// Pattern C — printf-style wrapped at the callsite (disassembly-only).
// The format string carries no code; the code is the function called on it.
//   return InvalidArgument(absl::StrFormat(template, shape, n));   // INVALID_ARGUMENT
//   return Internal(absl::StrFormat(template, ...));               // INTERNAL
// The family column is the best available signal without reading .text.

具有 "%s vs. %s" / "%d vs. %d" 比较形状的模板几乎总是验证器 INVALID_ARGUMENT(具有 InvalidArgument 的模式 C)；前缀为 TPU_RET_CHECK failure ( 的模板为 INTERNAL(模式 B)；其精确文字段出现在解压缩的 <Code>StrCat 符号中的模板肯定是 <Code>(模式 A)。

在 PJRT C-API 边界，absl::StatusCode 转换为 PJRT_Error_Code(四个 PJRT_Error_* 入口点 — PJRT_Error_Destroy、PJRT_Error_Message、PJRT_Error_GetCode、PJRT_Error_ForEachPayload — 和pjrt::PjrtErrorCodeToStatusCode 映射函数都存在)，因此 JAX/XLA 客户端通过插件句柄接收相同的规范分类法。请参阅 PJRT概述。

---

提示字符串(可行的补救措施)

与错误模板(格式字符串)不同，提示是在错误之后提供补救措施的可操作的散文 - 连接到调用站点的消息上。它们通过标记令牌进行划分，令牌本身发出面向用户与内部的信号：--flag=value / Reduce … memory / Please remove the hosts 是运营商自助服务； go/<link> / b/<id> / please file a bug 将用户指向 XLA/TPU 团队。每一个提示中命名的--flag都是一个真实注册的absl::Flag。提示的完整目录在 提示字符串 上；代表性切片：

地址	提示字符串(逐字记录，可能被截断)	级
0x858bb17	"Found a deeply - nested fusion … Please use --xla_tpu_rwb_fusion=false (and --xla_tpu_dot_dot_fusion=false if failure persists) …"	标志建议
0x96c35ed	"PartialReduce is designed to be used with fusion. Did you forget to set \--xla_tpu_nested_dot_fusion=true`?"`	标志建议
0xa074100	". Reduce TPU memory usage or set --jellyfish_executor_max_wait_time_for_releasing_memory_on_oom to a larger value."	容量/OOM
0xa07b361	"Not enough HBM spill stack available, please increase."	容量
0xa0c8b8d	"Encountered Dot op during TPU lowering that should have been eliminated during an earlier phase of compilation. This should not happen - please file a bug against XLA."	错误报告(内部)
0x858c562	"Kernel body fingerprint collision detected for key: %016x%016x. Please file a bug with the XLA team and provide the colliding kernel bodies."	错误报告(内部)
0xa011573	". See go/scoped-vmem for more details."	文档链接
0x9feecc8	"--xla_tpu_impure_enable_packed_bf16_math_ops is deprecated. Please use --xla_tpu_bf16_emission_mode in TpuCompilationEnvironment."	弃用

注意 — 深度嵌套融合补救字符串表条目从 0x858bb17 ("Found a deeply - nested fusion …") 开始。 0x858bbcf 是指向同一文字内的 "(1) Please use --xla_tpu_rwb_fusion=false …" 段的内部偏移量 - 使用条目起始地址 0x858bb17 进行逐字 grep。

明白了 — --flag=value 提示告诉您解决方法，这通常是非默认。 "Please use --xla_tpu_rwb_fusion=false"表示默认为true； "Did you forget to set --xla_tpu_nested_dot_fusion=true?"表示默认为false。将建议值视为默认方向信号，而不是确认的默认值 - 字节确认的默认值是一个单独的(较小的)集合。

"This should not happen - please file a bug against XLA." 系列是 0xa0c8b1e..0xa0c9758 上 TPU 降低不变检查的一个连续块，TPU 后端预计在降低之前已合法化的每个 HLO 操作(Dot、Call、BatchNorm 三重奏、Pad、Reverse、选择和分散、自定义/输出融合)。这些是纯粹的内部错误标记——它们永远不应该在格式良好的编译上触发。

---

超大规模误差聚合器

跨主机故障收集路径。当多切片作业挂起或出错时，每个 TPU 主机都会通过 MegaScaleTransport.ReportError gRPC 将 MegaScaleRuntimeError 发布到协调器；协调器的 ErrorReporter 将它们汇集到单个 MegascaleErrorAggregator 中，该 MegascaleErrorAggregator 将聚合分类为一个 Cause 并发出 RapidEyeErrorDigestProto 摘要。对超大规模误差聚合器进行全面处理；错误状态相关形状：

worker host 0..N  ──MegaScaleRuntimeError──▶  /MegaScaleTransport/ReportError
                                                       │
                                          coordinator: ErrorReporter::ReportError
                                                       │  (lazy-alloc one aggregator)
                                                       ▼
                                          MegascaleErrorAggregator::AddError
                                                       │  linked_hash_map upsert,
                                                       │  dedup key "slice:host/task_id"
                                                       ▼
                          when size()==NumWorkers()  or  300ms deadline fires
                                                       ▼
                                          ProcessAndShutdown() → classify Cause
                                                       ▼
                                          LogErrorDigest()  (per-Cause LOG(ERROR))
                                          WriteErrorDigestToStorage() (opt-in)
                                          optional LOG(FATAL) abort
```text

每个主机的 `MegaScaleRuntimeError.ErrorType` 是“输入”类别 — `NO_ERROR=0`、`HANG_DETECTED=1`、`UNRECOVERABLE_ERROR=2`、`CANCELLED=3`。聚合器对完整报告集运行事后分析，并发出一个 `RapidEyeErrorDigestProto.Cause`(跨主机*结论*)，每个都有自己的 `LOG(ERROR)` 补救散文：

| 原因值 | 名称 | 操作员补救措施(LOG(ERROR)散文) |
|---:|---|---|
| 0 | `UNKNOWN_CAUSE` | `"Megascale detects a hang but cannot determine the root cause. Please inspect the full digest below."` |
| 1 | `BAD_TPU_CHIP` | 张量核心芯片损坏→“从队列中删除主机并重新启动工作负载” |
| 2 | `FINGERPRINT_MISMATCH` | 不一致的 HLO 编译→“可能是 JAX 跟踪或 XLA 编译器中的错误……检查 HLO 转储” |
| 3 | `DATA_INPUT_STALL` | `"Please check the workers to make sure the data input pipeline is working properly."` (`0x9fd7519`) |
| 4 | `UNRECOVERABLE_ERROR` | “一些工作人员因不可恢复的错误而停止......检查这些工作人员的错误日志” |
| 5 | `DIFFERENT_MODULE` | “请确认所有工作人员都在运行完全相同的程序。” |
| 6 | `NETWORKING_ISSUE` | `"Please examine the underlying networking stack for the following hosts."` (`0x9ffc2f2`) |
| 7 | `BAD_SC_CHIP` | 稀疏核心芯片损坏→“从队列中删除主机并重新启动”(`0xa058553`) |
| 8 | `PROGRAM_NOT_QUEUED` | “检查您的应用程序是否被阻止/崩溃并阻止 JAX 排队下一个 TPU 程序” |

> **注意 —** 摘要是错误*范围仅限于主机*的唯一位置。单进程 `absl::Status` 命名一个 op 或一个 shape； Megascale 摘要将罪魁祸首命名为 `worker_id` / `host_name` / `chip_id` 集。聚合由 `--megascale_error_aggregation_enabled` 门控(默认开启)；摘要是否中止协调器由 `--megascale_error_reporter_abort_on_hang` / `--megascale_error_reporter_abort_on_error` 门控(两者均默认关闭 - 记录摘要，但除非设置，否则进程将继续存在)。
>
> **注意 —** 每个主机 `ErrorType` 枚举 (`NO_ERROR`/`HANG_DETECTED`/`UNRECOVERABLE_ERROR`/`CANCELLED`) 和跨主机 `Cause` 枚举是不同的。 `UNRECOVERABLE_ERROR` 两者都存在，但 `Cause` 是整个集合上的分类器*输出*，而不是输入类型的重新标记 - 例如所有 `HANG_DETECTED` 输入可以分类为 `BAD_TPU_CHIP`、`NETWORKING_ISSUE`、`DATA_INPUT_STALL` 等。重新实现时不要混淆这两个枚举。

---

## 交叉引用

- [错误模板](../runtime/error-templates.md) — 完整的 ~2937 模板表面、printf-vs-positional 习语、每个子系统模板列表
- [提示字符串](../runtime/hint-strings.md) — 完整的可操作提示目录(标志建议/文档链接/错误报告/容量/弃用/操作员操作)
- [超大规模误差聚合器](../megascale/error-aggregator.md) — `MegascaleErrorAggregator` 类布局、`RapidEyeErrorDigestProto` 接线格式、原因分类器、保留和中止策略
- [超大规模概述](../megascale/overview.md) — ErrorReporter 在 DCN 运行时中的位置
- [PJRT概述](../pjrt/overview.md) — 客户端边界的 `absl::Status` → `PJRT_Error_Code` 转换
- [超大规模跨主机屏障](../megascale/cross-host-barrier.md) — 共享位置 `$0/$1` 错误习语的屏障参与者验证器