Skip to main content

Troubleshooting

Common issues and how to resolve them.

No Data in Dashboard​

SymptomCheck
No spans or events appearingVerify endpointBaseUrl is reachable from the device
Data appears after a delaySpans are batched — check back after 30–60 seconds
SDK reports initialized but no dataConfirm dataCollectionState is .allowed, not .pending

Quick diagnostic:

print("SDK initialized:", Pulse.shared.isSDKInitialized())
print("SDK shutdown:", Pulse.shared.isShutdown)

Crashes Not Appearing​

  • Crashes are captured at fault time but uploaded on the next app launch. Force-kill a crash report test app, then relaunch — the report appears on that second launch.
  • Crashes cannot be tested with the debugger attached (LLDB intercepts signals). Run without a debugger attached or use TestFlight/device direct install.
  • Ensure crash { enabled(true) } is set (it's the default; only relevant if you disabled it).

Network Requests Not Appearing​

  • URLSession instrumentation is enabled by default. Check if you have a setShouldInstrument filter that is returning false for the requests you expect to see.
  • Requests to OTLP endpoints (/v1/traces, /v1/logs, /v1/metrics) are excluded automatically to prevent feedback loops — this is expected.
  • If you use a custom URLSession configuration, the SDK still instruments it via swizzling. Check that you are not using a URLProtocol that bypasses the system network stack.

Screen Lifecycle Not Tracking​

  • Screen lifecycle swizzles UIViewController. Pure SwiftUI apps that use NavigationStack without UIHostingController may not generate events for every navigation step. Ensure your app uses standard UIKit navigation or wraps SwiftUI in UIHostingController.
  • Verify screenLifecycle { enabled(true) } — it defaults to on, but double-check if you customized instrumentations.

Build Errors After Adding the SDK​

"No such module 'PulseKit'" — Make sure PulseKit is added to the correct target in Xcode, not just to the project. Check Target → General → Frameworks, Libraries, and Embedded Content.

Swift version mismatch — PulseKit requires Swift 5.10+. Check your target's Swift Language Version in Build Settings.

CocoaPods: framework not found — Run pod install again after any Podfile change, and open the .xcworkspace (not .xcodeproj).

Session Replay Not Recording​

  • Session replay is opt-in: Make sure to enabled it from remote config.
  • SwiftUI-only apps: session replay is UIKit-first. Screens driven entirely by SwiftUI (not backed by UIHostingController) may not record reliably.
  • Check that replayEndpointBaseUrl points to an endpoint that accepts replay data, or leave it nil to use endpointBaseUrl.

UIKit Tap Not Detecting Taps​

  • UIKit tap is opt-in: config.uiKitTap { $0.enabled(true) } must be set.
  • React Native apps: tap detection works via UIKit heuristics and will not identify RN Fabric component boundaries. See UIKit Tap for details.
  • If all taps appear as dead clicks, verify that the tapped views are UIControl subclasses, have UITapGestureRecognizer attached, or have .button / .link accessibility traits.

Location Attributes Missing​

  • Location is opt-in: config.location { $0.enabled(true) } must be set.
  • NSLocationWhenInUseUsageDescription must be present in Info.plist.
  • The user must grant location permission. If denied, location attributes are silently omitted.
  • Location is cached for 1 hour. Attributes may not update immediately if the device is moving.

SDK Initializes Twice​

The SDK ignores subsequent initialize() calls in the same process — the second call is a no-op (logged as a debug message). If you see this, check that you are not calling initialize() from multiple places (e.g., both AppDelegate and a scene delegate).

Still Having Issues?​

Contact the Pulse team at support@dreamhorizon.org with:

  • SDK version
  • iOS version and device model
  • Minimal code reproducing the issue
  • Any console output from [Pulse] log lines