docs(capture-exception): specify the ignored exception types option by posthog[bot] · Pull Request #95 · PostHog/sdk-specs

posthog · 2026-10-04T06:04:25Z

Problem

posthog-ios and posthog-android both ship errorTrackingConfig.ignoredExceptionTypes, but capture-exception never specified it. Their defaults only agreed once posthog-ios#894 changed the iOS default to [].

Changes

Adds an optional Ignored exception types requirement: empty default, every $exception path, whole chain, case-sensitive string matching, identifier form documented per SDK.
The archived proposal lists the SDK gaps still open: posthog-ios on watchOS/visionOS, the posthog-android server flavor, and posthog-kmp's posthog-ios pin from before #894.
Scenarios stay prose until the harness has steps for an ignore list; tagging and wiring them is a follow-up.

Testing

openspec validate --specs --strict passes 64/64 on 1.4.1, the version CI pins.

Agent context

DRI: @ioannisj
Autonomy: Human-driven (agent-assisted)

Created with PostHog Desktop

posthog-ios and posthog-android both expose errorTrackingConfig.ignoredExceptionTypes, and the spec said nothing about it. posthog-ios #894 changed its default from ["RCTFatalException"] to [], so the two now agree on the empty default. Records the shared contract: the option is optional; where it exists it defaults to empty, drops matching $exception events on every path before the capture pipeline, and matches case-sensitively across the whole exception chain. The matched identifier stays platform-idiomatic. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Generated-By: PostHog Desktop Task-Id: e399626d-2a51-4f82-bd36-0ca50f42eff2

…with SHALL

…gnored exception types

…ception types change

ioannisj · 2026-10-07T12:05:10Z

🤖 An AI agent wrote this on behalf of @ioannisj.

Picked this one up and pushed six fixes on top of the bot's commit:

The requirement opened with MAY, which the openspec 1.4.1 that CI pins rejects (it only reads the first line). It opens with SHALL now and the option is still optional. 29d2992
The identifier bullet said to rejoin module with type, but posthog-ios compares the bare type only. The bullet now describes both shipped forms (iOS bare type, Android isInstance plus module + type on the payload path), requires exact equality on whichever form the SDK documents, and gets a qualified-type scenario. e6a7c8b
proposal.md said posthog-ios conforms outright. On watchOS/visionOS the matcher is compiled out with the crash reporter, so a non-empty list drops nothing there. Qualified the note and called it an SDK gap rather than a reason for a spec carve-out. 55584b8
proposal.md said the RN plugin dedups via beforeSend. On Android it adds JavascriptException to ignoredExceptionTypes (posthog-js #4126), so I fixed that line. 81de0f9
proposal.md also said posthog-android conforms "including its server flavor". The server flavor gates captureException but not $exception events handed to the generic capture (it goes straight to captureStateless), so I qualified that line too. a0bded3
The archive folder was missing the .openspec.yaml every other archived change carries, so I added it. d8027d3

Also looked at scenario tagging, the no-throw clause having no scenario, and whether to mention posthog-js remote suppression rules; left those as they are.

dustinbyrne

AI-assisted review.

dustinbyrne · 2026-10-07T15:29:17Z

+
+## Impact
+
+Not a breaking change, and no SDK has to move: it records what posthog-ios and posthog-android


1. [P2 / MINOR] Include KMP in the archived rationale and impact analysis

Location: openspec/changes/archive/2026-10-04-specify-ignored-exception-types/proposal.md:46, RIGHT
Related location: design.md:8–9

The new blanket claim that “no SDK has to move,” together with “only the two mobile SDKs have it,” misses KMP’s supported public forwarding surface.

At KMP commit 7c2f4318a137d91718a84e52005ad3cf8a111ac3, applications can configure:

val errorTracking = ErrorTrackingConfig( ignoredExceptionTypes = emptyList() )

The public configuration exposes this option with an empty default. Apple setup appends its mapped values to the native ignore list rather than replacing that list.

KMP’s build declaration pins the native version exactly; its version catalog selects posthog-ios 3.64.1. The exact native source at that release defaults to ["RCTFatalException"].

Consequently, source inspection shows that ordinary KMP Apple setup with an empty common list retains the old native default. That differs from this PR’s new empty-default contract. KMP shares native matchers rather than providing a third independent implementation, but it still exposes the public option and has a separate dependency-alignment concern.

This is pre-existing SDK drift and newly inaccurate archive text, not a runtime regression caused by this specification PR. Its impact is an incomplete conformance inventory and migration assessment.

Consider describing these as two native implementations also exposed through KMP, adding the KMP dependency qualification alongside the existing platform gaps, and qualifying “no SDK has to move.” Keep the normative requirement and its optionality unchanged; no KMP implementation change is required in this PR.

Deterministic verification: Compare the cited public field, Apple append assignment, exact dependency declaration, version catalog, and native default. These sources were inspected directly. No automated behavioral regression test is applicable to the archive wording correction; the resulting native configuration was not executed.

🤖 An AI agent wrote this on behalf of @ioannisj.

Fixed in 4d9ec50. The archive now lists posthog-kmp as forwarding to the two native implementations, drops "no SDK has to move", and calls out that its exact posthog-ios 3.64.1 pin predates PostHog/posthog-ios#894, so KMP Apple apps on defaults still drop RCTFatalException until that pin moves.

KMP Android appends to posthog-android's empty list, so that side already conforms. Requirement text is unchanged, and the pin bump is KMP work.

turnipdabeets

The iOS and Android details check out. The description still ends with "Draft — please confirm the scope call above before merging". I'm fine with putting it in the spec even though only the mobile SDKs have it today, so consider that confirmed from my side.

turnipdabeets · 2026-10-07T15:36:01Z

+- Dropping SHALL be silent apart from a debug log, and SHALL NOT throw.
+- Matching SHALL consider every exception in the chain (every `$exception_list` entry, or every
+  link of the cause chain the SDK would serialize), not only the outermost one, and SHALL be
+  case-sensitive.


nit: since Android matches by class, case sensitivity only applies to string matching (iOS and the serialized-payload path). Might be worth saying so here, so the mynoisyerror scenario doesn't read as applying to Android's class list.

🤖 An AI agent wrote this on behalf of @ioannisj.

Scoped it in 90381ba. Case sensitivity now only applies where an SDK compares identifiers as strings (iOS, and Android's payload path), and the spec notes Android's Class list has no case to compare.

The mynoisyerror scenario is limited to string-matching SDKs too, so it no longer reads as applying to Android's class list.

turnipdabeets · 2026-10-07T15:36:01Z

+  equality in its documented form: posthog-ios compares the bare `type`; posthog-android rejoins
+  `module` and `type` into the qualified class name for events handed to the generic capture API.
+
+#### Scenario: default configuration drops nothing


nit: these scenarios are prose, while the rest of the spec uses the harness steps with an (@both) tag. Not blocking, but they'd need a @client-style tag to be wired up later.

Yeah I think this can come with the adapter work

…pes archive

…matching

ioannisj self-assigned this Oct 7, 2026

ioannisj added 5 commits October 7, 2026 14:31

fix(capture-exception): open the ignored exception types requirement …

29d2992

…with SHALL

docs(capture-exception): describe both shipped identifier forms for i…

e6a7c8b

…gnored exception types

docs(capture-exception): qualify posthog-ios conformance by platform

55584b8

docs(capture-exception): correct the React Native plugin note

81de0f9

docs(capture-exception): qualify the posthog-android server flavor note

a0bded3

ioannisj force-pushed the posthog/spec-ignored-exception-types branch from a816089 to a0bded3 Compare October 7, 2026 12:03

chore(capture-exception): add the archive metadata for the ignored ex…

d8027d3

…ception types change

ioannisj marked this pull request as ready for review October 7, 2026 12:05

ioannisj requested a review from a team as a code owner October 7, 2026 12:05

dustinbyrne approved these changes Oct 7, 2026

View reviewed changes

turnipdabeets approved these changes Oct 7, 2026

View reviewed changes

ioannisj added 2 commits October 8, 2026 16:50

docs(capture-exception): note posthog-kmp in the ignored exception ty…

4d9ec50

…pes archive

docs(capture-exception): scope case sensitivity to string identifier …

90381ba

…matching

ioannisj merged commit 73a3954 into main Oct 8, 2026
10 checks passed

ioannisj deleted the posthog/spec-ignored-exception-types branch October 8, 2026 16:37

Navigation Menu

Repository navigation

docs(capture-exception): specify the ignored exception types option - #95

docs(capture-exception): specify the ignored exception types option#95
ioannisj merged 9 commits into
mainfrom
posthog/spec-ignored-exception-types

posthog Bot commented Oct 4, 2026 •

edited by ioannisj

Loading

Uh oh!

ioannisj commented Oct 7, 2026

Uh oh!

dustinbyrne left a comment

Uh oh!

dustinbyrne Oct 7, 2026

Uh oh!

ioannisj Oct 8, 2026

Uh oh!

turnipdabeets left a comment

Uh oh!

turnipdabeets Oct 7, 2026

Uh oh!

ioannisj Oct 8, 2026

Uh oh!

turnipdabeets Oct 7, 2026

Uh oh!

ioannisj Oct 8, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## Impact

		Not a breaking change, and no SDK has to move: it records what posthog-ios and posthog-android

Conversation

posthog Bot commented Oct 4, 2026 • edited by ioannisj Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Changes

Testing

Agent context

Uh oh!

ioannisj commented Oct 7, 2026

Uh oh!

dustinbyrne left a comment

Choose a reason for hiding this comment

Uh oh!

dustinbyrne Oct 7, 2026

Choose a reason for hiding this comment

1. [P2 / MINOR] Include KMP in the archived rationale and impact analysis

Uh oh!

ioannisj Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

turnipdabeets left a comment

Choose a reason for hiding this comment

Uh oh!

turnipdabeets Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

ioannisj Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

turnipdabeets Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

ioannisj Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

posthog Bot commented Oct 4, 2026 •

edited by ioannisj

Loading