Issues

Issues are error events automatically grouped by fingerprint. Each issue has a status (new / in_progress / resolved / silenced / regressed / snoozed), a list of occurrences (affected sessions), comments, and version tracking for regression detection (semver-aware: 1.10.0 > 1.9.0).

Use these tools to investigate issues, update their status, merge duplicates, and add investigation notes.

Investigation workflow

To fully investigate an issue from discovery to resolution:

1. Find the issue — list-issues with project_id to see open issues sorted by severity. Filter status: "new" for uninvestigated issues.
2. Claim it — claim-issue to set status to in_progress, signaling you're investigating.
3. Read the detail — get-issue returns the issue with its occurrences array. Each occurrence has:
   • session_id — the session where the error occurred
   • user_id — the affected user (null if anonymous)
   • event_id — the specific error event
   • app_version / environment — which build and platform
4. Reconstruct breadcrumbs — For each occurrence, call investigate-event with the event_id to build the best timeline available: the full session (or a ±5 min window for events without a session_id), enriched with cross-app events (e.g. backend) for the same user in the same project. Merged, deduped, and sorted ascending by timestamp.
5. Read the error event — Use get-event with the occurrence's event_id to see full error details including custom_attributes (stack traces, error codes, etc.).
6. Iterate every occurrence, then look for patterns — Repeat steps 4-5 across the occurrences returned by get-issue — one breadcrumb is rarely enough; the goal is to surface what they have in common (same screen, same app_version, same user flow, same preceding step). If occurrence_has_more is true on the response, call get-issue again with the returned occurrence_cursor to walk the next page. For very high-frequency issues, a representative sample is fine — just sample broadly enough to be confident the pattern is real.
7. Document findings — add-issue-comment to record root cause, the common pattern across occurrences, affected versions, reproduction steps, or a fix plan. Visible to the whole team.
8. Resolve or escalate — resolve-issue with the fix version once patched (the version is required so regression detection has something to compare against). Use silence-issue if there's nothing to fix and you don't want to hear about it again. Use snooze-issue for suspected one-offs (auto-reopens on recurrence). Leave the comment for the team to act on otherwise.

list-issues

List issues for a project. Issues are error events grouped by fingerprint, sorted by severity (unique affected users). Filter by status, app, or dev/prod mode.

get-issue

Get details of a specific issue, including occurrences (sessions affected), comments, fingerprints, and linked attachments. The issue itself carries first_seen_app_version and last_seen_app_version — compare last_seen_app_version against the app's latest_app_version (from get-app) to tell whether the issue is still happening on the current release. Regression detection is semver-aware. See Latest Version Detection.

Each occurrence includes an event_id, session_id, user_id, app_version, and environment. For each occurrence, call investigate-event with the event_id to build the full breadcrumb trail (entire session + cross-app events for the same user in the same project) — that's the standard issue-investigation move and is far richer than a raw query-events call. Iterate across multiple occurrences to find common patterns before commenting or resolving.

Occurrences are paginated (default 50, max 200). When occurrence_has_more is true, call this tool again with the returned occurrence_cursor to walk the next page.

resolve-issue

Mark an issue as resolved. The fix version is required — it powers regression detection (any later version reporting the same error auto-flips the issue to regressed). If you don't have a fix version, use silence-issue (known issue, won't bother you again) or snooze-issue (suspected one-off — auto-reopens on next occurrence) instead.

silence-issue

Silence an issue to stop notifications. Occurrences are still tracked. The issue stays silenced even if it keeps happening — use snooze-issue instead if you want auto-reopen on recurrence.

snooze-issue

Snooze an issue. Same as silence-issue (no notifications, no fix version) but the next occurrence auto-reverts the issue to new and re-fires the issue.new push. Use when an error looks like a one-off and you only want to be alerted if the assumption turns out wrong.

reopen-issue

Reopen a resolved, silenced, or snoozed issue, setting status back to new.

claim-issue

Claim an issue by setting its status to in_progress. Use this when you start investigating or working on a fix.

merge-issues

Merge a source issue into a target issue. All occurrences, fingerprints, and comments are moved to the target. The source is deleted. Future events matching any merged fingerprint route to the surviving issue.

list-issue-comments

List comments on an issue in chronological order. Comments provide investigation context from users and agents.

add-issue-comment

Add a comment to an issue. Use this to document investigations, root causes, fixes, or context for future reference. Markdown is supported.