diagnosing-stacktrace-symbolication

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Diagnosing stack-trace symbolication

诊断堆栈跟踪符号化问题

Symbolication is the cross-platform name for what JavaScript source-map lookup, Hermes function-offset resolution, Proguard / R8 demangling, and dSYM address-to-line lookup all do — turn a minified or obfuscated frame back into a readable file, function, and line.

Work through the user's build and PostHog symbol sets as one pipeline: build config -> generated symbol artifacts (JavaScript source maps, Hermes maps, Proguard mappings, or dSYM bundles) -> uploaded symbol set in PostHog -> captured error frame. Most failures become obvious once those four pieces are checked in order.

符号化（symbolication）是一个跨平台术语，涵盖JavaScript源映射查找、Hermes函数偏移解析、Proguard / R8反混淆以及dSYM地址转行号等操作——其作用是将压缩或混淆的堆栈帧还原为可读的文件、函数和行号。

将用户的构建流程与PostHog符号集视为一个完整管道来排查：构建配置 → 生成的符号制品（JavaScript源映射、Hermes映射、Proguard映射或dSYM包） → PostHog中已上传的符号集 → 捕获到的错误帧。按顺序检查这四个环节后，大多数故障原因都会变得清晰。

Platforms

平台信息

Platform	Symbol-data type	Reference
JavaScript / TypeScript web	source-and-map	javascript.md
React Native (Hermes)	hermes	coming soon
Android (Proguard / R8)	proguard	coming soon
iOS / macOS (dSYM)	apple-dsym	coming soon

Step 3 of the workflow (symbol-set lookup in PostHog) is identical across platforms —

posthog-cli symbol-sets extract

handles all four container types. Steps 1, 2, and the platform-specific failure modes live in the per-platform reference.

平台	符号数据类型	参考文档
JavaScript / TypeScript Web	source-and-map	javascript.md
React Native（Hermes）	hermes	coming soon
Android（Proguard / R8）	proguard	coming soon
iOS / macOS（dSYM）	apple-dsym	coming soon

工作流的第3步（PostHog中的符号集查找）在各平台完全一致——

posthog-cli symbol-sets extract

可处理所有四种容器类型。第1、2步以及平台特定的故障模式记录在各平台参考文档中。

Workflow

排查工作流

Step 1 - Find how symbol data is produced and uploaded

步骤1 - 确定符号数据的生成与上传方式

Look at the app repo's build scripts and PostHog upload config. Confirm which PostHog package handles the upload (

@posthog/rollup-plugin

@posthog/webpack-plugin

@posthog/nextjs-config

@posthog/nuxt

, or direct

posthog-cli

) and which directory or asset it processes. See the platform reference for build-tool-specific config inspection.

For debugging, prefer a build where symbol artifacts remain on disk after upload so you can compare local artifacts against what PostHog received. JavaScript example with the Vite plugin (the platform reference covers the equivalent setting for other build tools):

sourcemaps: {
  enabled: true,
  deleteAfterUpload: false,
}

查看应用仓库的构建脚本和PostHog上传配置。确认负责上传的PostHog包（

@posthog/rollup-plugin

、

@posthog/webpack-plugin

、

@posthog/nextjs-config

、

@posthog/nuxt

或直接使用

posthog-cli

），以及它处理的目录或资源。请参考平台参考文档查看特定构建工具的配置检查方法。

为便于调试，优先选择上传后符号制品仍保留在磁盘上的构建方式，这样可以将本地制品与PostHog接收的内容进行对比。以下是Vite插件的JavaScript示例（平台参考文档包含其他构建工具的等效设置）：

sourcemaps: {
  enabled: true,
  deleteAfterUpload: false,
}

Step 2 - Build and inspect local artifacts

步骤2 - 构建并检查本地制品

Run the production build that uploads symbols, then inspect the emitted files locally. The exact files and helper invocation differ per platform — see the platform reference for the helper command, expected file shape, and common build-time pitfalls (notably empty-mappings false positives that look like upload bugs but are actually bundler config issues).

If local artifacts already look wrong, fix the build before debugging the PostHog upload.

运行会上传符号的生产构建，然后在本地检查生成的文件。具体文件和辅助命令因平台而异——请参考平台参考文档获取辅助命令、预期文件结构以及常见构建时问题（尤其是看起来像上传bug但实际是打包器配置问题的空映射误报）。

如果本地制品已经存在问题，请先修复构建，再调试PostHog上传流程。

Step 3 - Check symbol sets in PostHog

步骤3 - 检查PostHog中的符号集

Look up the symbol set whose

ref

matches the captured frame's

chunk_id

using the dedicated MCP tools — they handle auth, project scoping, and pagination automatically:

posthog:error-tracking-symbol-sets-list

with

ref=<chunk_id>

returns the matching row.

```
posthog:error-tracking-symbol-sets-retrieve
```
with the ID returns the same shape (and confirms permissions).
```
posthog:error-tracking-symbol-sets-download-retrieve
```
returns a one-hour presigned URL pointing at the uploaded symbol-data file. Download it immediately; do not echo the URL back unless the user explicitly asks.

If MCP access is not available, the same data is in Project settings > Error tracking > Symbol sets in the PostHog UI.

Interpret the row:

```
ref
```
must match the captured frame
```
chunk_id
```
.
```
last_used
```
updating means PostHog found and loaded that symbol set. It does not guarantee the frame resolved.
```
has_uploaded_file: false
```
means the upload did not complete.
A non-null
```
failure_reason
```
means PostHog could not parse or load the uploaded symbol data.

The downloaded file is a PostHog symbol-data container (compressed Rust-encoded payload), not plain JSON. Extract it with

posthog-cli

bash

posthog-cli symbol-sets extract symbolset.bin -o ./extracted

使用专用MCP工具查找

ref

与捕获帧的

chunk_id

匹配的符号集——这些工具会自动处理认证、项目范围和分页：

posthog:error-tracking-symbol-sets-list

搭配

ref=<chunk_id>

参数可返回匹配的记录。

```
posthog:error-tracking-symbol-sets-retrieve
```
搭配ID参数可返回相同结构的数据（并确认权限）。
```
posthog:error-tracking-symbol-sets-download-retrieve
```
会返回一个指向已上传符号数据文件的1小时有效预签名URL。请立即下载该文件；除非用户明确要求，否则不要返回URL。

如果无法访问MCP，可在PostHog UI的项目设置 > 错误追踪 > 符号集中查看相同数据。

解读记录内容：

```
ref
```
必须与捕获帧的
```
chunk_id
```
匹配。
```
last_used
```
更新意味着PostHog已找到并加载该符号集，但不保证帧已解析成功。
```
has_uploaded_file: false
```
表示上传未完成。
```
failure_reason
```
非空表示PostHog无法解析或加载已上传的符号数据。

下载的文件是PostHog符号数据容器（压缩的Rust编码 payload），不是纯JSON。使用

posthog-cli

提取内容：

bash

posthog-cli symbol-sets extract symbolset.bin -o ./extracted

or, without installing globally:

或者，无需全局安装：

npx @posthog/cli symbol-sets extract symbolset.bin -o ./extracted

bunx @posthog/cli symbol-sets extract symbolset.bin -o ./extracted


`posthog-cli symbol-sets extract` handles all four symbol-set types (source-and-map, hermes, proguard, dSYM) and
writes the extracted files into the output directory. Once extracted, summarize using the platform reference's
helper.


`posthog-cli symbol-sets extract`支持所有四种符号集类型（source-and-map、hermes、proguard、dSYM），并将提取的文件写入输出目录。提取完成后，请使用平台参考文档中的辅助工具进行汇总。

Step 4 - Compare local, uploaded, and served files

步骤4 - 对比本地、已上传和已部署文件

Use the failure location to decide what to compare:

Local artifact empty and uploaded artifact empty: build tool emitted unusable symbols.
Local artifact valid but uploaded artifact empty: upload processing selected or packed the wrong data.
Uploaded artifact valid but production stack stays minified or obfuscated: compare deployed binary bytes to the binary that was uploaded with the symbols.
```
Token not found
```
: PostHog loaded the symbol data but the captured generated position did not match any token in the uploaded artifact. Usually points to a changed binary after upload, wrong line / column capture (JavaScript) or wrong frame offset (Hermes / dSYM), or a symbol-coverage bug.

根据故障位置决定对比内容：

本地制品为空且已上传制品为空：构建工具生成了不可用的符号。
本地制品有效但已上传制品为空：上传处理选择或打包了错误的数据。
已上传制品有效但生产环境堆栈仍处于压缩或混淆状态：对比已部署二进制文件与上传符号时对应的二进制文件。
出现“Token not found”：PostHog已加载符号数据，但捕获到的生成位置与已上传制品中的任何token都不匹配。通常指向上传后二进制文件已更改、捕获的行/列信息错误（JavaScript）或帧偏移错误（Hermes / dSYM），或符号覆盖范围存在bug。

Step 5 - Fix the most likely layer

步骤5 - 修复最可能的问题层

Platform-neutral fixes:

Upload symbols after the final build output exists, not before a later step rewrites it.
Use the latest PostHog build plugin and
```
posthog-cli
```
.
Re-upload changed assets intentionally when the same
```
ref
```
was previously uploaded with different content.
Remove deployment-time transforms (CDN minify, edge rewrites, compression) that change the served binary after upload.

Platform-specific fixes live in the platform reference.

跨平台通用修复方案：

在最终构建输出生成后再上传符号，不要在后续步骤重写输出前上传。
使用最新版本的PostHog构建插件和
```
posthog-cli
```
。
当相同
```
ref
```
之前上传过不同内容时，主动重新上传已更改的资源。
移除部署时的转换操作（CDN压缩、边缘重写、压缩），这些操作会在上传后更改已部署的二进制文件。

平台特定修复方案请查看平台参考文档。

Captured frame checks

捕获帧检查

From an affected PostHog error event, collect one minified application frame:

```
filename
```
```
line
```
or
```
lineno
```
```
column
```
or
```
colno
```
```
function
```
```
chunk_id
```
(or platform-equivalent symbol-set ref)
any
```
resolve_failure
```
, especially
```
Token not found
```

The frame

filename

should match the deployed binary URL. The

chunk_id

should match the symbol set

ref

. The captured generated position should point into the same binary that was uploaded with the symbol data.

从受影响的PostHog错误事件中，收集一个压缩的应用帧信息：

```
filename
```
```
line
```
或
```
lineno
```
```
column
```
或
```
colno
```
```
function
```
```
chunk_id
```
（或平台等效的符号集ref）
任何
```
resolve_failure
```
，尤其是
```
Token not found
```

帧的

filename

应与已部署二进制文件的URL匹配。

chunk_id

应与符号集的

ref

匹配。捕获到的生成位置应指向与符号数据一起上传的同一二进制文件。

Failure matrix (cross-platform)

跨平台故障矩阵

Evidence	Likely cause	Next check
No `chunk_id` on frames	Chunk ID injection missing or SDK frame parser did not map the filename	Inspect deployed binary and raw frame filenames.
Symbol set row missing	Upload went to another PostHog project/host or skipped this asset	Compare plugin `projectId` , `host` , and `ref` .
`has_uploaded_file: false`	Upload did not finish	Check build logs; compare `posthog-cli` output to the symbol set row.
Non-null `failure_reason`	PostHog could not parse the uploaded symbol data	Download via Step 3 and inspect the extracted contents.
Uploaded artifact valid, deployed binary differs	Deployment/CDN/post-build transform changed the binary after upload	Compare deployed bytes to local build output.
`Token not found`	Captured position has no token in the uploaded symbol data	Verify captured position, deployed binary identity, and symbol-data coverage.

Platform-specific failure modes (empty

mappings

, missing

sourcesContent

, Hermes function-offset mismatch, Proguard class-name drift, dSYM UUID mismatch) live in the platform reference.

现象	可能原因	下一步检查
帧上没有 `chunk_id`	Chunk ID注入缺失，或SDK帧解析器未映射文件名	检查已部署二进制文件和原始帧文件名。
符号集记录缺失	上传到了其他PostHog项目/主机，或跳过了该资源	对比插件的 `projectId` 、 `host` 和 `ref` 。
`has_uploaded_file: false`	上传未完成	检查构建日志；对比 `posthog-cli` 输出与符号集记录。
`failure_reason` 非空	PostHog无法解析已上传的符号数据	通过步骤3下载并检查提取后的内容。
已上传制品有效，但已部署二进制文件不同	部署/CDN/构建后转换操作在上传后更改了二进制文件	对比已部署文件与本地构建输出。
出现“Token not found”	捕获到的位置在已上传符号数据中没有对应的token	验证捕获位置、已部署二进制文件标识以及符号数据覆盖范围。

平台特定故障模式（空

mappings

、缺失

sourcesContent

、Hermes函数偏移不匹配、Proguard类名漂移、dSYM UUID不匹配）请查看平台参考文档。