Chapter 02

Stack traces

The Trip details exception is in PostHog, but its stack trace points to Twig's minified code, so the engineers can't tell which line failed Fig. 1.

TypeError

Cannot read properties of undefined (reading 'name')

Fig. 1 – Without source maps, every frame points into a bundle.

Twig's web app is a minified React bundle. An app that uses one of these frameworks likely has the same issue:

Source map uploads

The engineers set up source map uploads for Twig's source code to get full stack traces. PostHog can get the maps three ways:

Option	Trade-off
Upload in CI	The default. The source stays private, and each build uploads its own maps.
Host them publicly	No upload step, but anyone can read the source.
Embed them in the bundle	No upload, but users download larger files and can read the source.

The engineers link each upload to a release. PostHog then shows the version and commit on every trace. With a GitHub or GitLab integration, it also links each frame to the file and line in PostHog/twig.com.

The engineers upload source maps in CI, which keeps Twig's source private. The Error Tracking Wizard sets up the upload step, so each build uploads its own maps. The Trip details trace now points at the failing line in readTripHost, in src/trips/trip-details.ts Fig. 2.

TypeError

Cannot read properties of undefined (reading 'name')

10export function readTripHost(hosts: Record<string, Host>, hostId: string) {
11 const host = hosts[hostId]
12 const hostName = host.name
13 return hostName
14}

Fig. 2 – With source maps, the same trace opens on the failing line in Twig's source code. Twig's own frames show at the top, and dependency frames carry a box icon.

Breadcrumbs

Breadcrumbs, which PostHog calls exception steps, hold context that only matters if something breaks. The engineers call addExceptionStep at checkpoints like a retry or a fallback path. The SDK attaches the steps to the next exception, and they show up in the issue's Timeline tab Fig. 3.

09:14:02/account/trips
09:14:06open_trip_detailsstay_id stay-02
09:14:07read_trip_hostsurface trip_details
09:14:07TypeErrorCannot read properties of undefined (reading 'name')
09:14:19/account/trips

exceptionexception steppageview

Fig. 3 – The Timeline tab shows your recorded steps in order, next to everything else in the session.

If no exception happens, the SDK discards the steps, so successful runs cost nothing.

The engineers pick where context goes by when they'll need it:

Record it as	When
An exception step	It only matters if this run fails
A log	The team wants it kept for every run, failed or not
A property on the exception	The team wants to filter, group, assign, or count issues by it
An event	The team wants to count the action on its own

Steps work in the web, React Native, iOS, Android, and Flutter SDKs.

Check your symbol setsAfter your next build, find your latest upload in the list.