diagnosing-stacktrace-symbolication

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,
}

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.

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:

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.

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.

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.