diagnosing-stacktrace-symbolication

Follow the five-step workflow: inspect your build config for the PostHog upload plugin, verify local source maps have non-empty mappings, check the symbol set row in PostHog for has_uploaded_file and failure_reason, then compare local, uploaded, and deployed files. The inspect_sourcemaps.py script summarizes map contents quickly.

Common causes include empty mappings emitted by the bundler, the deployed JS differing from the uploaded build, or a chunk_id mismatch between frames and symbol sets. Check the failure matrix to match your evidence to the likely layer.

Token not found means PostHog loaded the symbol data but the captured generated position matched no token in the uploaded artifact. It usually indicates the binary changed after upload, wrong line/column capture, or a symbol-coverage gap.

Yes, the workflow and symbol-set lookup steps are universal across JavaScript, React Native Hermes, Android Proguard/R8, and iOS/macOS dSYM. The posthog-cli symbol-sets extract command handles all four container types, though only the JavaScript platform reference is fully fleshed out.

Vite can emit structurally valid but data-less source maps when build.sourcemap is unset, because internal plugins like vite:css-post skip sourcemap generation. Set build.sourcemap to 'hidden' or true in vite.config to fix it.

Downloaded symbol sets are compressed binary containers, not plain JSON. Extract them first with posthog-cli symbol-sets extract, then run the inspect_sourcemaps.py script on the extracted directory to summarize the contents.