From ce3833a92550c4a33b98bb55db6edb31824dcda8 Mon Sep 17 00:00:00 2001
From: Philip Niedertscheider <phil.niedertscheider@sentry.io>
Date: Wed, 29 Jul 2026 13:28:34 +0200
Subject: [PATCH] docs(apple): Add replay overmask troubleshooting

---
 .../common/session-replay/troubleshooting.mdx | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/platforms/apple/common/session-replay/troubleshooting.mdx b/docs/platforms/apple/common/session-replay/troubleshooting.mdx
index 0d46733d1793e..f293393d25750 100644
--- a/docs/platforms/apple/common/session-replay/troubleshooting.mdx
+++ b/docs/platforms/apple/common/session-replay/troubleshooting.mdx
@@ -45,6 +45,36 @@ Text views, input views, images, video players and webviews are all masked by de
 
 </Expandable>
 
+<Expandable title="Why are parts of my replay completely masked?" permalink>
+
+Session Replay may mask an entire layer subtree if Core Animation raises an exception while the SDK inspects it. This privacy-safe fallback prevents the exception from crashing your app and avoids exposing content that the SDK could not inspect for sensitive data.
+
+A malformed `CABasicAnimation` is one possible cause. The animation's `fromValue` and `toValue` must use types compatible with each other and with the animated key path. For example, a `position` animation must use `CGPoint` values for both endpoints:
+
+```swift
+// Incorrect: mixes a scalar value with a CGPoint value.
+let animation = CABasicAnimation(keyPath: "position")
+animation.fromValue = NSNumber(value: 0)
+animation.toValue = NSValue(cgPoint: CGPoint(x: 100, y: 100))
+```
+
+```swift
+// Correct: both endpoints contain CGPoint values.
+let animation = CABasicAnimation(keyPath: "position")
+animation.fromValue = NSValue(cgPoint: CGPoint(x: 0, y: 0))
+animation.toValue = NSValue(cgPoint: CGPoint(x: 100, y: 100))
+```
+
+If your code creates the animation, correct the endpoint types. If a third-party UI library creates it, update the library and check its release notes for animation-related fixes.
+
+When SDK debug logging is enabled, a warning similar to the following confirms that Session Replay used this fallback:
+
+```text
+Caught Objective-C exception NSInvalidArgumentException: -[NSConcreteValue doubleValue]: unrecognized selector
+```
+
+</Expandable>
+
 <Expandable title="What's the lowest version of iOS supported?" permalink>
 
 Session Replay recording happens even on the lowest version supported by the Sentry SDK, which is aligned with App Store support.