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 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:]

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?
}

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

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

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 performance monitoring and network breadcrumbs.

Copied
import Sentry

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

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:

  1. Open your .xcproject in Xcode.
  2. Select your target in Xcode under "Targets".
  3. Navigate to "Frameworks, Libraries, and Embedded Content".
  4. Click on the "+" sign to open a dialog for choosing frameworks and libraries to add.
  5. Select "Sentry-Dynamic" and click "Add".
  6. Remove "Sentry" to ensure only "Sentry-Dynamic" appears under "Frameworks, Libraries, and Embedded Content".
  7. 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.

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").