Troubleshooting

Troubleshoot and resolve common issues with the Cocoa SDK.

Starting May 1, 2024, Apple requires all apps submitted to the App Store to provide a list of privacy-related APIs they use, including the reasons under which they use it. If you received an email from Apple with the message "ITMS-91053: Missing API declaration", your app doesn't fulfill the requirements. To solve this, follow our Apple Privacy Manifest guide.

Starting with iOS 15, the system might pre-warm your app by creating the process before the user opens it. In such cases, we can't reliably measure the app start, so we drop it as of sentry-cocoa 7.18.0. We are working on a fix for this. Follow the GitHub issue for more details.

We recommend updating to at least 7.18.1, or else the SDK might report too high a percentage of slow frames.

We recommend updating to at least 7.11.0, because before this version the SDK might falsely report out-of-memory crashes when an app hangs, and the user kills it manually.

We recommend updating to at least 7.5.3, because the HTTP instrumentation can lead to crashes. Alternatively, you can also disable the feature.

Since the introduction of screenshots for crashes in version 7.20.0, projects with 'enableCaptureScreenshot' enabled received duplicated crash reports. Therefore, we recommend updating to at least 7.25.0 to fix this problem.

If your project still initializes a UIWindow during application(_:didFinishLaunchingWithOptions:) and you plan to use an automatic UIViewController performance tracker, make sure to initialize your window, set the root view controller, and then initialize SentrySDK.

If you use Tuist to manage your SPM dependencies, add the following configuration to your Dependencies.swift under targetSettings

Copied

"Sentry": ["USE_HEADERMAP": "YES"]

"Sentry": ["USE_HEADERMAP": "YES"]

Sentry writes and reads files at a specific path in the app cache directory. This path is created during the SDK initialization. If you see a log message that looks like this: [SentryFileManager:439] Failed to write data to path it means that the cache path doesn't exist anymore. Check your app for any procedure that cleans the cache of your app during runtime, and avoid deleting the io.sentry directory.

Since Xcode 14 App Store Connect doesn't make debug symbols available for download anymore, see Xcode Release Notes. Please use a different way of uploading the debug symbols by following the documentation.

Suppose your app crashes in SentrySubClassFinder actOnSubclassesOfViewControllerInImage with a stacktrace similar to the one below:

Copied

#0	0x0000000000000000 in 0x00000000 ()
#1	0x00000001043eb498 in type metadata accessor for CapturedStructure? ()
#2	0x00000001043eb3ac in type metadata completion function for RoomCaptureTools ()
#3	0x000000018f9c7930 in swift::MetadataCacheEntryBase<(anonymous namespace)::SingletonMetadataCacheEntry, int>::doInitialization(swift::MetadataWaitQueue::Worker&, swift::MetadataRequest) ()
#4	0x000000018f9b8cf8 in swift_getSingletonMetadata ()
#5	0x00000001043eb360 in type metadata accessor for RoomCaptureTools ()
#6	0x00000001043eb314 in ObjC metadata update function for RoomCaptureTools ()
#7	0x000000018017d938 in realizeClassMaybeSwiftMaybeRelock(objc_class*, mutex_tt<false>&, bool) ()
#8	0x0000000180183548 in look_up_class ()
#9	0x00000001807e7cb8 in NSClassFromString ()
#10	0x000000010514b4c0 in __69-[SentrySubClassFinder actOnSubclassesOfViewControllerInImage:block:]

#0	0x0000000000000000 in 0x00000000 ()
#1	0x00000001043eb498 in type metadata accessor for CapturedStructure? ()
#2	0x00000001043eb3ac in type metadata completion function for RoomCaptureTools ()
#3	0x000000018f9c7930 in swift::MetadataCacheEntryBase<(anonymous namespace)::SingletonMetadataCacheEntry, int>::doInitialization(swift::MetadataWaitQueue::Worker&, swift::MetadataRequest) ()
#4	0x000000018f9b8cf8 in swift_getSingletonMetadata ()
#5	0x00000001043eb360 in type metadata accessor for RoomCaptureTools ()
#6	0x00000001043eb314 in ObjC metadata update function for RoomCaptureTools ()
#7	0x000000018017d938 in realizeClassMaybeSwiftMaybeRelock(objc_class*, mutex_tt<false>&, bool) ()
#8	0x0000000180183548 in look_up_class ()
#9	0x00000001807e7cb8 in NSClassFromString ()
#10	0x000000010514b4c0 in __69-[SentrySubClassFinder actOnSubclassesOfViewControllerInImage:block:]

Such a crash may be due to a potential bug in Swift that's triggered when trying to get a class definition that references a RoomPlan or ActivityKit class on an older iOS version that doesn't support RoomPlan or ActivityKit. For example, running the code below on iOS 15 with the Sentry Cocoa SDK enabled leads to the mentioned crash:

Copied

import RoomPlan

@available(iOS 17.0, *)
class RoomPlanWrapper {
    private var finalResults: CapturedStructure?
}

import RoomPlan

@available(iOS 17.0, *)
class RoomPlanWrapper {
    private var finalResults: CapturedStructure?
}

You can fix this by excluding the above class from swizzling by using swizzleClassNameExcludes, which is available with Sentry Cocoa SDK version 8.23.0 and above:

Copied

SentrySDK.start { options in
    options.swizzleClassNameExcludes = ["RoomPlanWrapper"]
}

SentrySDK.start { options in
    options.swizzleClassNameExcludes = ["RoomPlanWrapper"]
}

[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
     options.swizzleClassNameExcludes = [NSSet setWithObjects: @"RoomPlanWrapper", nil];
}];

[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
     options.swizzleClassNameExcludes = [NSSet setWithObjects: @"RoomPlanWrapper", nil];
}];

If you can't upgrade the Sentry Cocoa SDK to version 8.23.0, you can also disable swizzling, as shown below. However, this would also disable some useful features, such as automatic tracing and network breadcrumbs.

Copied

import Sentry

SentrySDK.start { options in
    options.enableSwizzling = false
}

import Sentry

SentrySDK.start { options in
    options.enableSwizzling = false
}

@import Sentry;

[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
    options.enableSwizzling = NO;
}];

#import <SentryObjC/SentryObjC.h>

[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
    options.enableSwizzling = NO;
}];

The errors, error: invalid version number in '-target arm64-apple-ios9999' and invalid version number in '-target arm64-apple-ios10.15-macabi', are due to a bug in Xcode. To fix this issue, update the Cocoa SDK to version 8.26.0 or above, or stay on version 8.21.0.

You can also try switching to Sentry-Dynamic when integrating the Cocoa SDK via Swift Package Manager with the following steps:

Open your .xcproject in Xcode.
Select your target in Xcode under "Targets".
Navigate to "Frameworks, Libraries, and Embedded Content".
Click on the "+" sign to open a dialog for choosing frameworks and libraries to add.
Select "Sentry-Dynamic" and click "Add".
Remove "Sentry" to ensure only "Sentry-Dynamic" appears under "Frameworks, Libraries, and Embedded Content".
Compile your project.

If you compile your project with Xcode 15.4 and none of the above works, Apple staff on the Apple forum say it is due to a bug in Xcode 15.4. They recommend sticking to Xcode 15.3 until Apple fixes this bug in a future Xcode release.

If the release health page shows fewer events in the unhandled tab, your events miss the unhandled property or mach info; please update the Cocoa SDK to version 8.33.0 or above or stay on version 8.30.0.

We introduced a bug with a refactoring #4101 released in 8.30.1, that caused unhandled/crash events to have the unhandled property and mach info missing, which is required for release health to show events in the unhandled tab. It's essential to mention that this bug doesn't impact release health statistics, such as crash-free session or user rates.

Since Cocoa SDK version 8.45.0 and above, you might see a compilation error 'required' initializer 'init(from:)' must be provided by subclass ..., when you subclass any of the following classes:

SentryBreadcrumb
SentryDebugMeta
SentryEvent
SentryException
SentryFrame
SentryGeo
SentryId
SentryMechanism
SentryMechanismMeta
SentryMessage
SentryNSError
SentryRequest
SentryStacktrace
SentryThread
SentryUser

You can fix this by not subclassing the affected classes. Strictly speaking, this is a breaking change, but these classes are not intended to be subclassed. If you have a strong reason to subclass them, please open a GitHub issue.

Cocoa SDK versions 8.51.1 and 8.52.0 have a bug that causes unsymbolicated stacktraces for non-fatal events, such ascaptureError, captureMessage or captureException. All or most stacktrace frames are then marked as redacted by Sentry. This bug doesn't impact fatal events or crashes.

Please update the Cocoa SDK to version 8.52.1 or above or stay on version 8.51.0 or below to fix this problem.

After updating to Cocoa SDK version 8.54.0, you might encounter build errors indicating that SentrySDK has no member capture or other API methods that were previously available, such as:

Copied

'SentrySDK' has no member 'capture'

'SentrySDK' has no member 'capture'

To resolve this problem try the following:

Clean your build by going to Product > Clean Build Folder in Xcode
Close all Xcode projects and close Xcode
Remove derived data by going to Xcode > Settings > Locations > Derived Data and clicking the arrow next to the path, then delete the folder for your project or, please be careful with the following command and double check the path, run rm -rf ~/Library/Developer/Xcode/DerivedData
Restart Xcode
Reset your package cache if using Swift Package Manager by going to File > Packages > Reset Package Caches
Rebuild your project

If you see a console error like:

Copied

[error] Could not parse the DSN: URL scheme of DSN is missing

[error] Could not parse the DSN: URL scheme of DSN is missing

This means the SDK received an invalid or empty DSN string. Common causes:

Setting options.dsn to an empty string or a malformed URL
A build configuration variable resolving to an empty value

Verify that the DSN you pass to options.dsn is a valid Sentry DSN URL starting with https://.

Cocoa SDK versions before 9.20.0 and 8.58.4 have a bug where, when one data type was rate limited (for example, user feedback), the SDK could also drop unrelated data such as errors, spans, and sessions. Please update the Cocoa SDK to version 9.20.0 or 8.58.4 or above to fix this problem.

This issue only affects projects that integrate Sentry via Swift Package Manager using the SentrySPM (compile from source) and build for arm64e using the Xcode IDE. The pre-built binary products (Sentry, Sentry-Dynamic) are not affected. Builds using xcodebuild or swift build are not affected.

When building for arm64e, Xcode may produce linker errors because SPM dependencies are not compiled for the arm64e architecture by default:

Copied

Undefined symbols for architecture arm64e: ...

Undefined symbols for architecture arm64e: ...

This is a known Xcode bug (Apple Feedback: FB23764103).

Add iOSPackagesShouldBuildARM64e = YES to your .xcworkspace/xcshareddata/WorkspaceSettings.xcsettings file. This tells Xcode to build SPM packages with arm64e support.

The iOSPackagesShouldBuildARM64e setting only affects iOS, macOS, and visionOS — tvOS, watchOS, and Mac Catalyst targets still hit the same linker error.

The workaround is to remove arm64e from the target's Architectures build setting in Xcode so the IDE build succeeds. When building with xcodebuild, override this by passing ARCHS="arm64 arm64e" on the command line so that arm64e is still included in CI and release builds. For more details, see sentry-cocoa #8426.

See Session Replay - Troubleshooting for more information.

Was this helpful?

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

How to contribute | Edit this page | Create a docs issue | Get support