面向用户的提示字符串

本页所有 offset 都是 libtpu-0.0.40-cp314 wheel（libtpu_lts_20260413_b_RC00，build-id md5 89edbbe81c5b328a958fe628a9f2207d，781,691,048 字节，ELF x86-64 DYN，not stripped）中进入 libtpu.so 的文件 offset（hex）。在此构建中 .rodata VMA == 文件 offset（1:1，base 0x84a0000），所以文件 offset 也是加载地址。其他 wheel 会不同。

摘要

本页编目 libtpu 的提示字符串：运行时和 XLA:TPU 编译器在错误旁边发出的建议性文字，用来告诉操作者或 JAX 用户应该对错误做什么。它们是 error-templates.md 中编目的原始错误/status 模板的可执行配套内容。错误模板陈述事实（"X must have rank >= N: got %s"），提示则追加补救办法（"Please use --xla_tpu_rwb_fusion=false"、"Reduce TPU memory usage"、"Please remove the hosts from the fleet"）。二者在 .rodata 中相邻，并在 .text 的 absl::StrCat/StrFormat callsite 处拼接；本页负责提示这一半及其触发条件/旋钮映射，而不是模板。

提示表面由五类 marker token 标出，token 的选择本身就是“由谁修复问题”的分类。--flag=value、"Reduce … memory" 和 "Please remove the hosts …" 是操作者可执行的 —— 用户有自助补救办法。b/<id>、go/<link> 和 "please file a bug" 会把用户指回 XLA/TPU 团队 —— 它们表示内部限制或已知问题，而不是用户可调整的旋钮。这一拆分（操作者可执行 vs 向上游报问题）是本页的主轴，并进一步细分为七个可执行性类别：flag-suggestion、doc-link、bug-report、capacity/OOM、deprecation、perf-tuning 和 operator-action。

这是一个参考目录，不是算法。每节按触发条件对提示分组，并且在二进制显示出来时，将提示与触发它的条件以及它命名的 flag/knob 配对。flag 名称是经字节确认的真实 absl::Flag 全局量（每个都有 AbslFlagHelpGenFor<name> 符号）；其帮助文本正文位于 config flag families，不在本页范围内。本页不声称知道每条提示拼接到了哪个错误模板上 —— 该关联是尚未追踪的 .text callsite（见未追踪）。

目录契约：

五类 marker token，以及它们如何区分操作者可执行与向上游报问题。
七个可执行性类别，每类按子系统分组其提示。
每条提示： 原始字符串、文件 offset，以及它引用的 flag/knob 或 tracker 坐标。
默认方向 caveat： 建议的 flag 值是 workaround 还是启用开关 —— 这是方向性判断，不是字节确认。


Section	`libtpu.so` 的 `.rodata`（base `0x84a0000`，file-offset == VMA）
Marker tokens	`--<flag>=<val>` · `go/<link>` · `b/<id>` · "file a bug" · "Reduce … memory"
不同的 `go/` 链接	54（514 次出现是 per-gen ISA-counter 文档，不是补救办法）
不同的 `b/<id>` id	31（均恢复了上下文）
Flag-suggestion 提示	~28 个字符串；抽查的 10/10 个 flag 均确认为已注册 `absl::Flag`
拼接 callsite	`.text` `absl::StrCat`/`StrFormat` — 未追踪（hint ↔ template 关联仍开放）

按触发条件速览：

可执行性类别	触发条件（什么会触发提示）	主要 token	计数（TPU/XLA 子集）
flag-suggestion	某个旋钮未设置/设置错误，或命中 fallback 路径	`--<flag>=<val>`	~28 个字符串
doc-link（action）	有文档化解决 playbook 的失败	`go/<link>`（非 counter）	~14
doc-link（ISA）	阅读 perf counter 的 ISA 规范	`go/<gen>-isa#anchor`	514 occ / ~16 distinct
bug-report	内部 invariant 破坏 / 未实现路径	"file a bug" · `b/<id>`	~40 prose + 31 `b/<id>`
capacity / OOM	HBM/VMEM/Smem 压力，分配失败	"Reduce … memory" · OOM	~15
deprecation	使用了已移除/迁移中的 flag 或功能	"deprecated" · "no longer"	~7
perf-tuning	走到了次优但正确的代码路径	"suboptimal" · "inefficient"	~6
operator-action	fleet/topology/sequencing 补救，无 bug-id	"Please …" · "Ensure …"	~25

五类 Marker Token

提示表面是通过在字符串表上对五个 token 家族执行 rg 定位到的。它们不只是搜索锚点 —— 一条提示携带的 token 能可靠预测其可执行性类别，因为 libtpu 的作者一致地使用每类 token。

text

--<flag>=<value>     OPERATOR-ACTIONABLE  → set this knob and retry
"Reduce … memory"    OPERATOR-ACTIONABLE  → free HBM / raise a limit
"Please remove …"    OPERATOR-ACTIONABLE  → fleet/topology remedy
go/<link>            FILE-IT-UPSTREAM     → read the team's doc/playbook
b/<id>               FILE-IT-UPSTREAM     → known issue, comment/track
"please file a bug"  FILE-IT-UPSTREAM     → internal invariant broke
```text

> **NOTE —** 这个拆分是启发式，不是硬分区：单条提示可以同时携带两者（`0xa083064` 处的 "…suboptimal MXU throughput … Please file a bug with XLA:TPU compiler team, and use `--xla_tpu_accumulate_into_mrb=false` in the meantime." 同时是 bug-report 和 flag-suggestion）。当提示混合 token 时，本目录将其归在主要补救办法下，并交叉注明。
>
> **GOTCHA —** `go/` 和 `b/` token 主要由*不可执行*用法占据。约 640 次 `go/` 出现中有 514 次是嵌入硬件 perf counter 描述字符串中的 per-gen ISA-spec 链接（`[counter](http://go/glc-sc-isa#anchor)`），不是错误补救办法。重新实现者如果只 grep `go/` 来扫描“可执行提示”，会被 counter 文档淹没；请过滤到非 counter 集合（[Doc-Link 提示](#doc-link-提示-golink)）。

---

## Flag-Suggestion 提示

自助补救类别：错误或日志行命名一个具体的 `--xla_*` / `--megascale_*` / `--tpu_*` / `--deepsea_*` flag 及其应设置的值。下面每个被命名的 flag 都通过其 `AbslFlagHelpGenFor<name>` 符号确认为已注册的 `absl::Flag` 全局量（抽查 10/10 均 1:1 resolved；flag 帮助文本正文属于 config 章节）。

### Fusion / MXU

| Offset | 提示字符串（原文） | 引用的 flag |
|---|---|---|
| `0x858bbcf` | "(1) Please use --xla_tpu_rwb_fusion=false (and --xla_tpu_dot_dot_fusion=false if failure persists), Reason: found fallback window config while lowering fusion." | `xla_tpu_rwb_fusion`, `xla_tpu_dot_dot_fusion` |
| `0xa2b7034` | (`0x858bbcf` 的重复 — 同一个 rwb/dot_dot fusion 补救；两份拷贝逐字节相同) | （同上） |
| `0x96c35ed` | "PartialReduce is designed to be used with fusion. Did you forget to set \`--xla_tpu_nested_dot_fusion=true\`?" | `xla_tpu_nested_dot_fusion` |
| `0xa083064` | "…suboptimal MXU throughput on this HLO. Please file a bug with XLA:TPU compiler team, and use --xla_tpu_accumulate_into_mrb=false in the meantime." | `xla_tpu_accumulate_into_mrb` |

### SparseCore / embedding

| Offset | 提示字符串（原文） | 引用的 flag |
|---|---|---|
| `0x9fe2e58` | "If you are seeing this error when attempting to compile a distributed embedding model try running with --xla_tpu_embedding_table_oblongness_threshold=1 to ensure the embedding table is not given a tiled layout." | `xla_tpu_embedding_table_oblongness_threshold` |
| `0xa073044` | "Skipping reduce-scatter decomposition as SC ND RS needs --xla_tpu_enable_sparse_core_reduce_scatter_v2=true." | `xla_tpu_enable_sparse_core_reduce_scatter_v2` |
| `0xa07b05e` | "Number of sparse cores for scatter offloading should not be 0. To disable, please set xla_tpu_enable_offloading_scatter_to_sparsecore to false." | `xla_tpu_enable_offloading_scatter_to_sparsecore` |
| `0xa07b0ee` | "Number of SparseCores for gather offloading should not be 0. To disable, please set xla_tpu_enable_offloading_gather_to_sparsecore to false." | `xla_tpu_enable_offloading_gather_to_sparsecore` |
| `0x85c0718` | "Unsupported: computing max_nz_per_row requires --xla_sc_fused_scatter_in_compute_loop" | `xla_sc_fused_scatter_in_compute_loop` |
| `0x85c076e` | "Unsupported: computing max_unique_nz_per_row requires --xla_sc_fused_scatter_in_compute_loop" | `xla_sc_fused_scatter_in_compute_loop` |
| `0x85c07cb` | "Unsupported: computing max_unique_nz_per_row requires --xla_sc_fused_gather_in_compute_loop" | `xla_sc_fused_gather_in_compute_loop` |
| `0x86678da` | "…To avoid this failure, try to set a larger number to '--fdo_config_sparsecore_allowed_dropped_id_count_per_epoch' flag" | `fdo_config_sparsecore_allowed_dropped_id_count_per_epoch` |

### Scheduler / collective / infeed

| Offset | 提示字符串（原文） | 引用的 flag |
|---|---|---|
| `0xa008ce4` | "…has gaps on the way from that operand to itself. You can use --xla_tpu_scheduling_annotation_deannotate_unsupported_groups=true to deannotate the unsupported groups." | `xla_tpu_scheduling_annotation_deannotate_unsupported_groups` |
| `0xa060e03` | "Attempted to use profile-guided latency estimator without the real cost model. Either enable --xla_tpu_scheduler_using_real_cost_model or unset --xla_tpu_impure_latency_hiding_scheduler_profile_path." | `xla_tpu_scheduler_using_real_cost_model`, `xla_tpu_impure_latency_hiding_scheduler_profile_path` |
| `0xa04a55e` | "Sinking DCN collectives requires --xla_tpu_use_megascale_host_reduction." | `xla_tpu_use_megascale_host_reduction` |
| `0xa05844c` | "Sharded infeed with non-uniform layouts is not supported. Try turning off the infeed layout optimization (--transpose_tpu_infeed=false) and report to XLA team." | `transpose_tpu_infeed` |

### Memory / OOM / runtime / debug

| Offset | 提示字符串（原文） | 引用的 flag |
|---|---|---|
| `0x9e6e39e` | "…Aborting compilation early because it's unlikely to have enough device memory. Requires %s, has %s available. If more detailed logging is desired, set --xla_tpu_impure_oom_fast_exit_threshold=-1" | `xla_tpu_impure_oom_fast_exit_threshold` |
| `0xa074100` | ". Reduce TPU memory usage or set --jellyfish_executor_max_wait_time_for_releasing_memory_on_oom to a larger value." | `jellyfish_executor_max_wait_time_for_releasing_memory_on_oom` |
| `0xa01af59` | "Spilling sregs to HBM on megacore is implemented but untested; use --xla_enable_megacore_hbm_spill=true to activate, and please update b/177274769 with findings." | `xla_enable_megacore_hbm_spill` |
| `0xa07a6ba` | ". Restart the job or disable set --megascale_use_numa_aware_threadpool=false." | `megascale_use_numa_aware_threadpool` |
| `0x96deddc` | "…bytes. Pass --xla_hbm_logging_buffer_size_bytes=&lt;n&gt;" | `xla_hbm_logging_buffer_size_bytes` |
| `0xa06c059` | "Unable to log from the tile because tile log is NOT enabled. Use --xla_tpu_enable_tile_log_recorder=true to enable logging." | `xla_tpu_enable_tile_log_recorder` |
| `0xa06c0d5` | "…was invoked but logging was not enabled. Use --xla_tpu_enable_sc_log_recorder=true to enable logging." | `xla_tpu_enable_sc_log_recorder` |
| `0xb52d9a0` | "You need to set --deepsea_chips_per_host_bounds, --deepsea_host_bounds to match your setup. Contact tfrt-devs@ if you have any questions." | `deepsea_chips_per_host_bounds`, `deepsea_host_bounds` |
| `0x96c2015` | "…the threadpool for tensorflow operations is too small.  Try increasing --45eac_num_operation_threads and please notify barna-core-devs@" | `_45eac_num_operation_threads` (BarnaCore) |
| `0x9fff409` | "Very slow compile? If you want to file a bug, run with envvar XLA_FLAGS=--xla_dump_to=/tmp/foo and attach the results." | `xla_dump_to` |
| `0xa00da29` | "…if you would like to reliably retrieve the error message, try running it again with --notpu_use_continuations." | `tpu_use_continuations`（取反） |
| `0x87fb08b` | "[enable stack trace via --xla_jf_collect_llo_stack_trace]" | `xla_jf_collect_llo_stack_trace` |

### 默认方向 caveat

> **GOTCHA —** 提示让你设置的值不一定是默认值的*反面*；要读动词。"use `--flag=false` … in the meantime" / "Please use `--flag=false`" 这类提示（`rwb_fusion`、`dot_dot_fusion`、`accumulate_into_mrb`）命名的是 **workaround**（用非默认 toggle 逃离坏路径）。"use `--flag=true` to enable" 这类提示（`tile_log_recorder`、`sc_log_recorder`、`sparse_core_reduce_scatter_v2`、`nested_dot_fusion`）命名的是一个**默认关闭**的功能，其中 `=true` 是启用开关。把这些当成默认方向；只有约 13 个由 rodata 证明的默认值经过字节确认（config 章节）。不要假设建议值等于“默认值”。

---

## Doc-Link 提示（`go/<link>`）

`go/` shortlink token 可以清晰拆成一个小的**可执行 playbook**集合，以及一个大的 **ISA-counter-documentation** 家族。只有前者是补救办法；后者是 profiler 附到 perf counter 上的参考资料。

### 可执行 / playbook 链接（TPU/XLA 相关）

| `go/` 链接 | 提示字符串（offset） | 子系统 |
|---|---|---|
| `go/scoped-vmem` | `0xa011573` ". See go/scoped-vmem for more details." | MSA / scoped VMEM |
| `go/sc-dynamic-bounded-slice` | `0xa050247` "DynamicBoundedSlice lowering is only supported inside of custom fusions, see go/sc-dynamic-bounded-slice for more information." | SparseCore lowering |
| `go/xla_compile_runtime_flag_error` | `0xa047216` "Runtime flags … must be set consistently between compile options and ABSL flags. … See go/xla_compile_runtime_flag_error for resolution." | compile-env flag 一致性 |
| `go/megascale-debug-playbook` | `0xa21a318` "Debug dumping triggered. Refer to go/megascale-debug-playbook for further debugging. megascale_debug_dir = " | megascale runtime |
| `go/jfc-errata` | `0x8644f10` / `0xa0d46d9` / `0xa0ee662` "…See errata entry go/jfc-errata#&lt;anchor&gt;"（counter-errata caveat） | JXC ISA errata |
| `go/llvm-crash-bug` | `0xa033687` "invalid profile created. Please file a bug at: <http://go/llvm-crash-bug> and include the profraw files that caused this error." | PGO / LLVM crash report |

> **NOTE —** 这些是用户可用于*解决* TPU/XLA 失败的唯一 `go/` 链接。第二簇（`go/protection-key-fault`、`go/general-protection-fault`、`go/stacktraces`、`go/cppstackoverflow`、`go/lsan`、`go/prod-naming-1-5`、`go/grpc-without-init-google-exemption`、`go/streamz-force-collection`、`go/no_file_or_rpc_during_init`、`go/redact-debug-string`）来自静态链接的 Google library 文本（signal handler、sanitizer、gRPC、telemetry），不是 TPU 特定代码路径。它们存在于二进制中，但不是 libtpu 补救办法；将其视为 library 噪声（MEDIUM 相关性）。

### Per-gen ISA-counter 文档链接（主体：514 次出现）

`go/` 的主要用途**不是**补救。profiler 暴露的每个硬件性能 counter 都在其*描述*字符串中携带指向 ISA-spec 小节的 Markdown 链接，例如 `0xa0dcfac` "This counter counts hold-scalar-issue cycles for `[yN_reserved](http://go/vfc-sc-isaa#yn-reserved)`." 链接前缀编码 TPU 代际：

```text
go/jfc-isa, go/jfc-errata                       JXC  (Jellyfish / Dragonfish)
go/pfc-isa, go/pfc-sc-isa, go/pfc-bc-isa,
  go/pfc-memory-system                          PXC  (Pufferfish)
go/vfc-sc-isa (94+ occ), go/vfc-mem             VXC vector-fetch-core (Viperfish)
go/vxc-isa, go/vxc-sc-isa                        VXC ISA (Viperfish / Ghostlite vector)
go/glc-isa, go/glc-sc-isa (94 occ)              GXC general-load-core (Ghostlite)
go/gfc-isa, go/gfc-sc-isa (97 occ), go/gfc-power GXC general-fetch-core
go/core (70 occ)                                generic core-doc anchor

QUIRK — 这些链接中有一个在发布的二进制中拼错了：go/vfc-sc-isaa（已在 0xa0dcfac 确认，多了一个 a）。重新实现者若复现 counter-description 语料，应保留这个拼写错误以逐字节匹配此构建，不要“修复”它。完整 counter→anchor 表是另一项大型提取，本页不枚举。

Bug-Report 提示

向上游报问题的类别。这些 prose 字符串把用户指向 tracker、团队或 b/<id> 已知问题。它们表示用户命中了内部限制，而不是可调整旋钮。

带 tracker 坐标的 "file a bug" prose

Offset	提示字符串（原文，缩略）	目标
`0x9f1d09c`	"DeepseaPlatform and --tpu_use_tfrt=false are now deprecated. … please file a bug at: https://b.stripped_domain/issues/new?component=670280"	tracker component 670280 (TFRT)
`0xa039ed8`	"RoutingTableAnalyzer detects a potential deadlock! File a bug against SliceBuilder (https://b.stripped_domain/issues/new?component=503036). Please attach core dumps retrieved from Coroner."	tracker component 503036 (SliceBuilder)
`0xaf0bf90`	"Please report a bug at: https://github.com/google/jax/issues/new?assignees=apaszke"	github.com/google/jax（公开）
`0xab9e630`（also `0xaba4a30`/`0xaba4b70`/`0xaba4c50`）	"Please file a bug under Platforms > Performance > BarnaCore > Software with repro instructions"	BarnaCore component path（×4）
`0x858c562`	"Kernel body fingerprint collision detected for key: %016x%016x. Please file a bug with the XLA team and provide the colliding kernel bodies."	XLA team
`0x8a2941d`	"Fatal error in creation of RWB Fusion. Please file a bug with XLA-TPU"	XLA-TPU
`0x96c1211`	"XLA has not implemented dynamic sized slice with non-trival stride yet. Please file a bug against XLA"	XLA
`0x96c12d4`	"Unimplemented reduce-window in fusion cost modeling. Please file a bug with XLA"	XLA
`0x96c1fd3` / `0xa0c9b76`	"Allocated address is not aligned, please file a bug to tfrt-devs@" / "Duplicate allocation found, please file a bug to tfrt-devs@."	tfrt-devs@
`0xa036ccd`	"… is an unsupported memory space in TpuCustomCallScopedVmemAdjuster. Please file a P2 feature request, against the XLA-TPU team …"	XLA-TPU (P2 FR)
`0xa03eb45` / `0xa03eb8b`	"Manual sub-axis isn't supported. Please file a bug with a reproducer." / "Non-divisible sharding with unreduced axes isn't supported. …"	XLA (Shardy)
`0xa1b0507`	"The auto-sharding solver could not find a valid solution within the given time limit. Please report this as a bug!"	XLA (auto-sharding)

TPU-lowering invariant 块（`0xa0c8b1e..0xa0c9758`）

一段连续的 "should not happen" 模板，每个对应一个 TPU 后端期望在 lowering 前已被 legalise 掉的 HLO op。这些是纯内部 bug marker —— 没有用户补救办法。该块连续但并非严格同质：这一段的第一个字符串 0xa0c8b1e 是关于layout 而不是未消除 op 的 sibling 变体 —— "Encountered mismatched layouts for select-and-scatter. This should not happen - please file a bug against XLA." 真正的 "Encountered <Op> op during TPU lowering…" 模板从 0xa0c8b8d（Dot）开始。

text

0xa0c8b1e  Encountered mismatched layouts for select-and-scatter.
           This should not happen - please file a bug against XLA.
0xa0c8b8d  Encountered <Op> 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.
   <Op> ∈ { Dot, Call, BatchNormTraining, BatchNormInference, BatchNormGrad,
            Pad, Reverse, select-and-scatter, custom-fusion, OutputFusion, … }   (~14 ops)
```text

### `b/<id>` 已知问题 / TODO 引用（31 个不同 id）

这些将限制钉到已追踪 bug 上。除了“评论/跟踪”外不可执行 —— 用户最多是在 bug 上留注。下面列出 31 个不同 id 中的代表性行。

| `b/<id>` | 上下文（offset） | 类别 |
|---|---|---|
| `b/167392593` | `0xa00f6f4`（×4）"TODO(b/167392593): Support {bitcasts merging dims, sliced prefetches, …}." | MSA/prefetch TODO |
| `b/177274769` | `0xa01af59` "…use --xla_enable_megacore_hbm_spill=true … please update b/177274769 with findings." | megacore HBM spill |
| `b/433785288` | `0xa041d37` "…fixed by Shardy partitioner in the future, tracked in b/433785288. Contact Shardy or XLA team for help." | Shardy partitioner |
| `b/36072659` | `0xa0af6ba` "Infeed buffer size … bug in the infeed operation (b/36072659). See the bug for a workaround …" | infeed deadlock |
| `b/147787375` | `0x99e1405` / `0x99e144d` "Close() appears to be hanging, this might be a deadlock see b/147787375" / "Disable() appears to be hanging, …" | runtime deadlock |
| `b/282055166` | `0x9929df3` "Error may indicate firmware queue fullness: b/282055166" | runtime/firmware |
| `b/30481585` | `0xa12ba16` "Device reset is not yet supported on this platform (b/30481585)" | runtime/device-reset |
| `b/488336614` | `0xa0a0fb0` "b/488336614 Only single-SC element scatter add is supported." | SparseCore scatter |
| `b/422762004` | `0xa12c03b` "Gather with implicit convert is not supported. (b/422762004)" | gather lowering |
| `b/343490729` | `0x87050df` "Not implemented: TODO(b/343490729): stores packed int2 are not supported" | int2 lowering |

> **NOTE —** 指向*workaround* 的 `b/<id>` id（`b/36072659` infeed、`b/494604538` cancellables）是这一类最接近可执行的情况；其余只用于进度跟踪。6 位数最小 `rg` 阈值意味着更短的 `b/<id>` 或 `cl/<id>` changelist 引用可能存在但低于阈值（完整性 LOW confidence）。

---

## Capacity / OOM 提示

操作者可执行的内存压力类别：释放内存、提高限制，或等待 compaction。按检测压力的位置分组。

### 编译期和运行时 OOM

| Offset | 提示字符串（原文，缩略） | 补救 |
|---|---|---|
| `0x9e6e39e` | "Aborting compilation early because it's unlikely to have enough device memory. Requires %s, has %s available. … set --xla_tpu_impure_oom_fast_exit_threshold=-1" | 编译期 OOM abort + logging knob |
| `0xa074100` | ". Reduce TPU memory usage or set --jellyfish_executor_max_wait_time_for_releasing_memory_on_oom to a larger value." | runtime OOM → 释放内存或等待更久 |
| `0xa07b361` | "Not enough HBM spill stack available, please increase." | 增加 HBM spill stack |
| `0xa04bde4` | "Allocation fails. Try again after compaction. Please note that compaction can be slow. If you want to achieve better performance, please manage TPU buffers carefully to avoid this compaction." | compaction 后重试（capacity + perf） |

### Embedding capacity

| Offset | 提示字符串（原文，缩略） | 触发条件 |
|---|---|---|
| `0xa01cc4f` | "TPU embedding: out of memory allocating %lld bytes." | embedding HBM 分配 |
| `0xa030f0a` | "The current embedding configuration does not fit on the TPU due to HBM space constraints or more optimization algorithms than supported: aggregate_min_resource_count (%d) > total_resource_count (%d)." | embedding 配置超过 HBM/optimizer 资源 |
| `0xa056bd4` | "The number of unique optimizers in the TPU embedding configuration exceeds the capacity of the TPU system." | 不同 optimizer 过多 |
| `0xa07d172` | "Scatter operand has %d elements, which exceeds the 32-bit limit. Unsupported on SparseCore." | SparseCore 32-bit index 限制 |

### Fusion / VMEM / Smem capacity guard

| Offset | 提示字符串（原文） | 限制 |
|---|---|---|
| `0x84b1b50` / `0x84b1b7d` / `0x9fd4955` | "Nested dot fusion would exceed vmem capacity" / "Custom Fusion would exceed vmem capacity" / "' exceeds VMEM capacity." | VMEM-capacity fusion guard |
| `0x84b1a2b` / `0xa1b5992` | "Smem high-water mark exceeds memory capacity" / "SCS high-Smem usage exceeds Smem capacity" | Smem capacity |
| `0x9ff331b` | "The input tensor is not on HBM/VMEM and it exceeds the HBM logging buffer limit." | HBM logging-buffer cap（与 `--xla_hbm_logging_buffer_size_bytes` 配对） |
| `0xa1eed4d` | "Too many buffers are colored in the alternate memory. Could not reserve alternate memory for colored output of instruction " | alternate-memory coloring |
| `0xa122204` / `0xa122248` | "The size of next-hop routing table (%d) exceeds the chip limit (%d)" / "The size of routing table (%d) exceeds the chip limit (%d)" | ICI routing-table cap |

> **NOTE —** VMEM/Smem/routing-table guard 是*容量拒绝*，不是补救办法 —— 它们告诉用户命中了限制，但不命名 flag。可执行 OOM 提示（`xla_tpu_impure_oom_fast_exit_threshold`、`jellyfish_executor_max_wait_time_for_releasing_memory_on_oom`）也属于 flag-suggestion，并已在上文交叉出现。

---

## 弃用通知

数量很少，且主要是 flag 迁移。排除 library 中 "constexprs are no longer supported" 风格的噪声；只列出 TPU/XLA 通知。

| Offset | 通知（原文，缩略） | 迁移 |
|---|---|---|
| `0x9f1d09c` | "DeepseaPlatform and --tpu_use_tfrt=false are now deprecated. This flag is slated for removal. …" | 移除；如果仍需要则 file bug |
| `0x9feecc8` | "--xla_tpu_impure_enable_packed_bf16_math_ops is deprecated. Please use --xla_tpu_bf16_emission_mode in TpuCompilationEnvironment." | → `xla_tpu_bf16_emission_mode` |
| `0x8a293e0` | "Non-SPMD model parallelism is no longer supported by XLA:TPU" | 使用 SPMD |
| `0xa26350a` | "[DEPRECATED_XLA_TPU_FLAG_USE] Deprecated TpuCompilationEnvironment flags were overridden: " | runtime marker（flags overridden） |
| `0xa2ad13b` | "[DEPRECATED_XLA_TPU_FLAG_USE] Deprecated TpuCompilationEnvironment flags were present and not matching their default values:" | runtime marker（非默认 deprecated flag） |
| `0xa0b19dd`（also `0xa0b1a9a`） | "The SegmentShardingHelperDivSimple class can only be used when … BarnaCores per row per task is equal to 1 … Use the SegmentShardingHelperDiv class instead."（also `…ModSimple` → `…Mod`） | BarnaCore class 迁移 |
| `0xa0b1c7c` | "DescriptionForDevice.* is not supported for TPU. Please use one of the GetExecutor methods instead." | → `GetExecutor` methods |

> **NOTE —** 两个 `[DEPRECATED_XLA_TPU_FLAG_USE]` 字符串是运行时 marker，runtime 会在 deprecated `TpuCompilationEnvironment` flag 被设置时打印它们；它们作为违规 flag 列表的前缀，而不是命名单个 flag。deprecated-flag *名称*本身属于 config 章节。

---

## 性能调优建议

"Suboptimal but correct" 通知：代码路径有效，但用户可以做得更好。

| Offset | 建议（原文，缩略） |
|---|---|
| `0xa083064` | "…suboptimal MXU throughput on this HLO. … use --xla_tpu_accumulate_into_mrb=false in the meantime."（也是 flag-suggestion + bug-report） |
| `0x9fd3a5e` | ". Switch to allocate_output to avoid performance penalty." |
| `0x9ff1304` | "Concatenate fusion is inefficient." |
| `0xa041d37` | "…SPMD will replicate the tensor and then partition it … which is inefficient. … tracked in b/433785288." |
| `0xa29fd14` | "Layout inefficient dot whose output shape has small lane/sublane dimensions" |
| `0xa04bde4` | "…If you want to achieve better performance, please manage TPU buffers carefully to avoid this compaction."（也是 capacity 提示） |

> **NOTE —** MSA 旋钮 `xla_tpu_msa_inefficient_use_to_copy_ratio`（`0xbfc053e` 处的 proto 字段）是 "inefficient use-to-copy" perf 路径*背后*的启发式；它在 config 层命名，而不是在提示字符串中命名（LOW confidence：是否有任何面向用户的提示直接打印它）。

---

## 操作者动作文本

不带 bug-id 的自助补救：fleet/topology 动作、op sequencing 协议、init/lifecycle 指引，以及团队指针。

### Megascale hang digest（8 个 cause-branch 补救）

每个 "Megascale detects a hang that is likely caused by `<cause>`. `<remedy>`." 字符串都命名一个随检测到的 cause 变化的不同操作者动作。cause→remedy *dispatch*（哪个 `Cause` enum 选择哪个字符串）是 `.text` switch，**未追踪**。

| Offset | Cause → remedy（原文，缩略） |
|---|---|
| `0xa058553` | bad TPU **sparse core** chips → "Please remove the hosts from the fleet and restart the workload. If problem persists please contact Megascale XLA team." |
| `0xa05862f` | bad TPU **tensor core** chips → "Please remove the hosts from the fleet and restart the workload. …" |
| `0x9ffc2f2` | networking issue → "Please examine the underlying networking stack for the following hosts." |
| `0x9fd7519` | data-input stall → "Please check the workers to make sure the data input pipeline is working properly." |
| `0xa06d7d2` | different modules on different devices → "Please confirm that all workers is running the exact same program. …" |
| `0xa079562` | inconsistent HLO module compilation → "This is likely a bug in JAX tracing or XLA compiler. Please inspect the HLO dumps …" |
| `0xa0d7cec` | worker not queuing programs → "Check if your application is blocked/crashing and preventing JAX to queue the next TPU program (jitted functions)." |
| `0x9fe02ae` | unknown cause → "Megascale detects a hang but cannot determine the root cause. Please inspect the full digest below." |

关联 abort：`0xa045c93` "Aborting the coordinator as an unrecoverable error is reported …"；`0xa045d37` "Aborting the coordinator after collecting errors … as megascale_error_reporter_abort_on_hang is set to true …"。

> **QUIRK —** bad-SC-chips（`0xa058553`）和 bad-TC-chips（`0xa05862f`）的补救英文近乎相同，但有一个词的语法漂移（"If problem persists" vs "If the problem persists"）。它们是两个不同的 rodata 字符串，每个 cause-branch 一个，不是单个共享模板 —— 构建 digest 的重新实现者必须按 cause 发出匹配变体，不要去重。

### TPU embedding op-sequencing 协议（`0xa009da1..0xa04698b`）

约 10 条 "Ensure that … before …" 提示强制执行 embedding-parameter op 顺序（`load_` → `retrieve_` → `enqueue_`/infeed）。它们描述 JAX/TF-TPU 用户必须遵循的严格 op-protocol；底层 state machine 未在此追踪。

```text
"Cannot retrieve embedding parameters … until the previous retrieve/load operation
 has completed. Ensure that the previous … ops have completed before …"

"TPU embedding infeeds cannot be run in the middle of retrieving/loading the embedding
 parameters. Please quiesce all infeeds before retrieving/loading parameters and restart
 the infeeds after … is complete. Ensure that the retrieve_/load_tpu_embedding_*_parameters
 ops have completed before the enqueue_tpu_embedding_*_batch ops are run."   (0xa046624 / 0xa046853)

"Embedding parameters can be loaded … only after the TPU system has been first initialized.
 Ensure that the load_… ops are run only after tpu.initialize_system() is complete."

Init / driver-lifecycle 提示

Offset	提示（原文，缩略）
`0x9fe0d47`	"Failed to get tpu system. Please call tf.tpu.experimental.initialize_tpu_system() before running any ops on tpu."
`0x9fd4688`	"PjRtClient already exists for TPU. This probably means you have already implicitly initialized PJRT. … call tf.tpu.experimental.initialize_tpu_system() explicitly …"
`0xa094bb2`	"No TPU_SYSTEM device found. Please ensure that you're connected to a host with a TPU_SYSTEM device."
`0x9fe65a1`	"Failed to initialize TPU system, please contact Cloud TPU Support."
`0xa07188f`	"WARNING: could not determine %s, please set env var `%s` manually, otherwise libtpu.so may not properly initialize."
`0xa1e3f95`	"Are you using the right LibTPU version? This LibTPU is built for <…>"
`0xa1a96ba`	"executable is built for device %s of type "%s"; cannot run it on device %s of type "%s""
`0xa0012c5`	"… DMA buffers were still outstanding when the driver was destroyed. … please ensure all buffers are destroyed before destroying driver objects."
`0xa079d96`	"TPU driver close was incomplete; kernel reported %d device handles outstanding. … Ensure that all userspace access to the device has ended before invoking driver close."
`0x9ffb075`	"Lost connection to the SliceBuilder controller task (normally worker task 0). Please check controller task status."
`0xa1fd28c`	"Please ensure that you have only created one TPUEmbedding"

联系团队指针

text

tfrt-devs@         alignment / allocation / topology-bounds bugs
barna-core-devs@   embedding hot-id-replication threadpool sizing
Shardy team / XLA  manual-axes / unreduced-axes sharding
Megascale XLA team persistent hang after host removal
Cloud TPU Support  TPU-system init failure (the one external channel)
```text

---

## CPU-Feature 启动 Guard（`go/sigill-fail-fast`）

一个致命 pre-main guard：如果主机 CPU 缺少此构建要求的 ISA feature，它会 abort。`0xbe7d460+` 处有 12 个变体，每个 feature 一个：

```text
FATAL ERROR: This binary was compiled with <isa> enabled, but this feature is not
available on this processor (go/sigill-fail-fast).
   <isa> ∈ { aes, avx, mmx, pclmul, popcnt, sse, sse2, sse3,
             sse4.1, sse4.2, ssse3, cmpxchg16b }                 (12 variants)

NOTE — 这是来自静态链接 Google 代码的 absl CPU-feature startup guard，不是 TPU 特定路径 —— 它告诉操作者其主机 CPU 对该构建来说过旧。本页包含它，是因为它是带 go/ 补救链接的面向用户致命文本，但它不是 libtpu 补救办法。早先的 error-template 目录命名了 12 个变体中的 11 个；第 12 个 cmpxchg16b 已确认存在于 0xbe7d460+（CERTAIN）。

未追踪

本页是诊断表面的提示半边；与表面其余部分的若干链接被有意留开，因为它们需要本目录没有做的反汇编。

Hint ↔ error-template 关联。 提示在 .rodata 中与其父错误模板相邻，但拼接发生在 .text 的 absl::StrCat/StrFormat callsite。每条提示追加到错误模板表面的哪一项上 —— 以及得到的 absl::StatusCode —— 未追踪。
默认方向。 flag-suggestion 的建议值是默认值还是 workaround，是 DefaultDebugOptions() / FLAGS_* ctor 问题，不是每个 flag 都经过字节确认（只有约 13 个 rodata-evidenced default 是）。上面的基于动词的启发式是方向性的，不是权威结论。
日志严重级别。 每条提示以何种严重级别发出（WARNING / ERROR / FATAL）由 callsite 设置，除非 prose 自身写明 "FATAL" / "Aborting" / "WARNING"。
Megascale cause→remedy dispatch。 已恢复 8 个 hang-digest 字符串，但 Cause-enum → string switch 未追踪。
go/<link> 内容解析到二进制中不存在的 Google 内部 URL；只恢复了链接 token 和引用 prose。
go/<gen>-isa#anchor → counter map。 514 次出现的 ISA-doc-link 家族只按 gen-codename 映射汇总；per-counter anchor 表是另一项大型提取。

交叉引用

Error Templates — 这些提示会追加到的原始 error/status 模板；模板是事实，提示是补救办法。
Runtime Overview — 诊断表面位于运行时的何处。
Internal Pass Names — 许多 "should not happen during TPU lowering" bug-report 提示中出现的 pass/lowering 名称。
Flag Families (config) — 这些提示命名的已注册 absl::Flag 全局量，以及其帮助文本正文和默认值。
XLA Flag Atlas (config) — flag-suggestion 提示指向的完整 --xla_tpu_* / --megascale_* knob 目录。

面向用户的提示字符串 ​

摘要 ​

五类 Marker Token ​

Bug-Report 提示 ​

带 tracker 坐标的 "file a bug" prose ​

TPU-lowering invariant 块（0xa0c8b1e..0xa0c9758） ​

Init / driver-lifecycle 提示 ​

联系团队指针 ​

未追踪 ​

交叉引用 ​

面向用户的提示字符串

摘要

五类 Marker Token

Bug-Report 提示

带 tracker 坐标的 "file a bug" prose

TPU-lowering invariant 块（`0xa0c8b1e..0xa0c9758`）

Init / driver-lifecycle 提示

联系团队指针

未追踪

交叉引用