/investigating-error-issue

name: investigating-error-issue
description: >
  Investigates a single PostHog error tracking issue end-to-end. Use when
  the user provides an issue ID or pastes an issue URL
  (`/error-tracking/<id>`) and wants to understand the error — who it
  affects, what triggers it, when it started, whether it correlates with
  a release, browser, OS, or feature flag, and what the next step should
  be. Pulls aggregated metrics, sample exception events, segment
  breakdowns, linked replays, and synthesizes a hypothesis-grade summary
  in one pass.

Investigating an error tracking issue

When a user asks "what's going on with this error?" or pastes an issue URL, gather the context they would otherwise have to assemble manually: who is hitting it, what changed, where it happens, and whether a replay shows the cause.

Available tools

| Tool | Purpose | | ------------------------------------------- | ------------------------------------------------------------------------------------------- | | `posthog:query-error-tracking-issue` | Compact issue details (status, assignee, top frame, release, aggregates) | | `posthog:query-error-tracking-issue-events` | Sampled `$exception` events with stack, URL, browser, `$session_id` | | `posthog:execute-sql` | Breakdowns, release / flag correlations, surrounding events + console logs around the error | | `posthog:query-logs` | OTEL log entries around the error timestamp for server-side issues | | `posthog:query-session-recordings-list` | Linked replays (delegate ranking to `finding-replay-for-issue`) | | `posthog:read-data-schema` | Confirm property keys before filtering on them |

Workflow

Step 1 — Establish the issue baseline

Fetch the issue record with its compact aggregates and a sparkline:

posthog:query-error-tracking-issue
{
  "issueId": "<issue_id>",
  "dateRange": { "date_from": "-30d" },
  "includeSparkline": true,
  "volumeResolution": 12
}

Capture: `name`, `description`, `status`, `first_seen`, `last_seen`, `assignee`, total `occurrences` / `users` / `sessions`, top in-app frame, latest release metadata, and the volume buckets.

The sparkline tells you the shape — flat, spike, ramp, or recurring — and that shape drives the rest of the investigation. If the user only asked a status question, skip `includeSparkline` to save tokens.

Step 2 — Pull a sample exception event

A captured event has the stack frames, URL, browser, and properties needed to reason about cause. Pull a recent sample first, then an early one to compare.

posthog:query-error-tracking-issue-events
{
  "issueId": "<issue_id>",
  "limit": 1,
  "include": ["exception", "stacktrace", "environment", "navigation", "correlation"]
}

The tool defaults to `onlyAppFrames: true`, which strips vendor frames; flip to `false` when the bug appears to live in a third-party library — or when the response comes back with `stacktrace.type: "resolved"` but no frames at all (common for minified bundles where every frame looks vendor-y to the resolver, e.g. React production builds).

For the earliest sample, narrow `dateRange` to a tight window around the issue's `first_seen` (e.g. set `date_from` slightly before and `date_to` slightly after) and pass `orderDirection: "ASC"` so you get the earliest event in the window rather than the latest — the tool defaults to `DESC`, which would return a recent event and silently duplicate the first call. If recent and earliest events look materially different — different stack root, different URL pattern — the issue may be a grouping mistake. Flag for `grouping-noisy-errors` instead of continuing as if it were one bug.

Step 3 — Run breakdowns to isolate the cause

Breakdowns aren't a typed tool — drop into `execute-sql`. Run only the breakdowns the issue's shape suggests; each one costs a query and clutters the synthesis.

| Sparkline shape | First breakdown to try | | ----------------- | ------------------------------------------------------------------------ | | Spike from zero | By app version / release — almost always a deploy regression (see below) | | Steady-state high | By browser / OS — rendering or platform-specific bug | | Ramp | By geography or feature flag — gradual rollout exposure | | Bursts then quiet | By time of day or `$current_url` — scheduled job or specific page |

Picking the right version property

PostHog emits three version-shaped fields. They mean different things and only one of them answers "what version of the user's app introduced this?":

| Property | What it is | Auto-captured by | Use for | | --------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `$exception_releases` | Cymbal-managed release map, keyed by release ID | Only when SDK publishes release metadata (e.g. sourcemap upload tied to a release) | Most precise release attribution **when present** | | `$app_version` | The user's deployed app version | iOS (`CFBundleShortVersionString`), React Native (Expo / react-native-device-info) | "What deploy of my app introduced this?" — the question users care about | | `$lib_version` | The Pos