fix(errors): emit $exception_list in canonical order (caught-first, root cause last)

[cat-ph]

Problem

posthog-python is the only SDK that emits $exception_list with the root cause first. Every other SDK with exception-chain support puts the caught/outermost exception at index 0. exceptions_from_error_tuple() walked the chain in caught-first order and then called .reverse(), flipping it to root-cause-first.

This is the Python side of the cross-SDK exception-ordering standardization: PostHog/sdk-specs#11.

Canonical order: $exception_list[0] = the caught/outermost exception; each cause is appended after its wrapper in unwrap order; the root cause is last.

Change

• Removed the .reverse() in exceptions_from_error_tuple() (posthog/exception_utils.py). Both build paths already produce the list in canonical order:
  • plain chained exceptions: walk_exception_chain yields caught-first, following __cause__ / __context__;
  • ExceptionGroup: exceptions_from_error keeps the group (parent) before its contained exceptions.
• Added an explanatory comment documenting the canonical order and why we do not reverse.
• Frame order within each stacktrace is untouched (already bottom-up / canonical).

No code in the SDK or the Django integration derives values from $exception_list positions (e.g. no issue-name/type/message picking off [0]), so there is no downstream code change needed in this repo.

Tests

Added regression tests in posthog/test/test_exception_capture.py:

• explicit cause (raise B from A) -> asserts [0] is the caught B and the last entry is root cause A;
• implicit context chain (exception raised while handling another) -> same ordering;
• ExceptionGroup (3.11+) -> asserts the group is first, members follow.

uv run pytest posthog/test/test_exception_capture.py posthog/test/test_client.py -> 145 passed (re-run after rebase onto current main). Ruff lint + format clean.

Coordination

BREAKING wire-order change. The ordering of $exception_list on the wire flips. Merge/release only after the pipeline normalization gate (cymbal) is live, so the pipeline can normalize incoming order based on $lib_version. Shipping this as a MINOR release (changeset included) so the pipeline can gate on the version. This flip should be paired with fingerprint aliasing on the pipeline side, since exception/frame fingerprints are order-sensitive.

User-visible effects

Anything downstream that reads $exception_list[0] (issue fingerprinting / naming, primary exception type + message) will now see the caught/outermost exception instead of the root cause. That is the intended, canonical behavior and matches the other SDKs — but it is a visible change for existing Python-sourced issues.

[greptile-apps]

_{Reviews (1): Last reviewed commit: "chore: use pypi/posthog changeset key" | Re-trigger Greptile}

[github-actions]

posthog-python Compliance Report

Date: 2026-07-03 00:25:55 UTC
Duration: 177118ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	516ms
Format Validation.Event Has Uuid	✅	1506ms
Format Validation.Event Has Lib Properties	✅	1505ms
Format Validation.Distinct Id Is String	✅	1504ms
Format Validation.Token Is Present	✅	1506ms
Format Validation.Custom Properties Preserved	✅	1505ms
Format Validation.Event Has Timestamp	✅	1505ms
Retry Behavior.Retries On 503	✅	9517ms
Retry Behavior.Does Not Retry On 400	✅	3504ms
Retry Behavior.Does Not Retry On 401	✅	3506ms
Retry Behavior.Respects Retry After Header	✅	9513ms
Retry Behavior.Implements Backoff	✅	23512ms
Retry Behavior.Retries On 500	✅	7515ms
Retry Behavior.Retries On 502	✅	7509ms
Retry Behavior.Retries On 504	✅	7509ms
Retry Behavior.Max Retries Respected	✅	23515ms
Deduplication.Generates Unique Uuids	✅	1506ms
Deduplication.Preserves Uuid On Retry	✅	7513ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	14519ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7506ms
Deduplication.No Duplicate Events In Batch	✅	1501ms
Deduplication.Different Events Have Different Uuids	✅	1506ms
Compression.Sends Gzip When Enabled	✅	1505ms
Batch Format.Uses Proper Batch Structure	✅	1505ms
Batch Format.Flush With No Events Sends Nothing	✅	1004ms
Batch Format.Multiple Events Batched Together	✅	1504ms
Error Handling.Does Not Retry On 403	✅	3507ms
Error Handling.Does Not Retry On 413	✅	3508ms
Error Handling.Retries On 408	✅	7512ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	1001ms
Request Payload.Flags Request Uses V2 Query Param	✅	1005ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	1005ms
Request Payload.Flags Request Omits Authorization Header	✅	1004ms
Request Payload.Token In Flags Body Matches Init	✅	1006ms
Request Payload.Groups Round Trip	✅	1005ms
Request Payload.Groups Default To Empty Object	✅	1005ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	1004ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	1005ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	1005ms
Request Lifecycle.No Flags Request On Init Alone	✅	503ms
Request Lifecycle.No Flags Request On Normal Capture	✅	1505ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	1009ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	1001ms
Retry Behavior.Retries Flags On 502	✅	1005ms
Retry Behavior.Retries Flags On 504	✅	1005ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	1509ms