# Troubleshooting

## Troubleshoot and resolve common issues with the Cocoa SDK.

## ["Missing API declaration" after App Store review](#missing-api-declaration-after-app-store-review)

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](/platforms/apple/data-management/apple-privacy-manifest/) guide.

## [Wrong App Start Data](#wrong-app-start-data)

Starting with iOS 15, the system might [pre-warm](https://developer.apple.com/documentation/uikit/app_and_environment/responding_to_the_launch_of_your_app/about_the_app_launch_sequence#3894431) 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](https://github.com/getsentry/sentry-cocoa/releases/tag/7.18.0). We are working on a fix for this. Follow the [GitHub issue](https://github.com/getsentry/sentry-cocoa/issues/1897) for more details.

## [High Slow and Frozen Frames Rate](#high-slow-and-frozen-frames-rate)

We recommend updating to at least [7.18.1](https://github.com/getsentry/sentry-cocoa/releases/tag/7.18.1), or else the SDK might report too high a percentage of slow frames.

## [Falsely Reported Out Of Memory Crashes](#falsely-reported-out-of-memory-crashes)

We recommend updating to at least [7.11.0](https://github.com/getsentry/sentry-cocoa/releases/tag/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.

## [Crashes with HTTP Auto Performance Instrumentation](#crashes-with-http-auto-performance-instrumentation)

We recommend updating to at least [7.5.3](https://github.com/getsentry/sentry-cocoa/releases/tag/7.5.3), because the HTTP instrumentation can lead to crashes. Alternatively, you can also [disable the feature](/platforms/apple/tracing/instrumentation/automatic-instrumentation/#http-instrumentation).

## [Duplicated Crashes Event With Screenshots](#duplicated-crashes-event-with-screenshots)

Since the introduction of screenshots for crashes in version [7.20.0](https://github.com/getsentry/sentry-cocoa/releases/tag/7.20.0), projects with 'enableCaptureScreenshot' enabled received duplicated crash reports. Therefore, we recommend updating to at least [7.25.0](https://github.com/getsentry/sentry-cocoa/releases/tag/7.25.0) to fix this problem.

## [My first view controller has no performance trace](#my-first-view-controller-has-no-performance-trace)

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.

## [I use Tuist and the project crashes when I update Sentry](#i-use-tuist-and-the-project-crashes-when-i-update-sentry)

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

```Swift
"Sentry": ["USE_HEADERMAP": "YES"]
```

## [SentryFileManager: Failed to write data to path](#sentryfilemanager-failed-to-write-data-to-path)

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.

## [My app is not symbolicated and I use App Store Connect](#my-app-is-not-symbolicated-and-i-use-app-store-connect)

Since Xcode 14 App Store Connect doesn't make debug symbols available for download anymore, see [Xcode Release Notes](https://developer.apple.com/documentation/xcode-release-notes/xcode-14-release-notes#Deprecations). Please use a different way of uploading the debug symbols by following the [documentation](/platforms/apple/dsym/).

## [Unknown receiver '\<SomeReceiver>', Use of undeclared identifier '\<SomeIdentifier>'](#unknown-receiver-somereceiver-use-of-undeclared-identifier-someidentifier)

If you see an error like `Unknown receiver 'SwiftDescriptor'` or `Use of undeclared identifier 'SentryLog'` during the application build process, there's a conflict stemming from `APPLICATION_EXTENSION_API_ONLY`. By default, the Sentry Cocoapod is configured with `APPLICATION_EXTENSION_API_ONLY=YES`, but some `post_install` script likely changed it. To fix this error, add the following to the `Podfile`.

`ios/Podfile`

```ruby
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      if target.name == 'Sentry'
        config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'YES'
      else
        # configuration for other targets
      end
    end
  end
end
```

## [Crash in `SentrySubClassFinder.actOnSubclassesOfViewControllerInImage`](#crash-in-sentrysubclassfinderactonsubclassesofviewcontrollerinimage)

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

```bash
#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](https://github.com/apple/swift/issues/72657) 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:

```swift
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:

```swift
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 tracing and network breadcrumbs.

```swift
import Sentry

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

## [Xcode Compiler Error: Invalid Version](#xcode-compiler-error-invalid-version)

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](https://forums.developer.apple.com/forums/thread/751573) 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.

## [Release Health Misses Unhandled Events and Missing Mach Info](#release-health-misses-unhandled-events-and-missing-mach-info)

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](https://github.com/getsentry/sentry-cocoa/pull/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.

## [Sandbox Error Using Cocoapods](#sandbox-error-using-cocoapods)

After setting up Cocoapods using a `Podfile` and running `pod install` to set up the project, you might see the following error when building the target:

```bash
error: Sandbox: rsync.samba(42924) deny(1) file-read-data <path/to/your/app>/Frameworks/Sentry.framework/Sentry.bundle (in target 'test' from project 'test')
error: Sandbox: rsync.samba(42925) deny(1) file-read-data <path/to/your/app>/Frameworks/Sentry.framework/_CodeSignature/CodeResources (in target 'test' from project 'test')
error: Sandbox: rsync.samba(42925) deny(1) file-write-create <path/to/your/app>/Frameworks/Sentry.framework/_CodeSignature/.CodeResources.a2sA9v (in target 'test' from project 'test')
mkdir -p <path/to/your/app>/Frameworks
rsync --delete -av --filter P .*.?????? --links --filter "- CVS/" --filter "- .svn/" --filter "- .git/" --filter "- .hg/" --filter "- Headers" --filter "- PrivateHeaders" --filter "- Modules" "<path/to/derived/data>/Sentry/Sentry.framework" "<path/to/your/app>/Frameworks"
building file list ... done
rsync: opendir "<path/to/your/app>/Frameworks/Sentry.framework/Sentry.bundle" failed: Operation not permitted (1)
IO error encountered -- skipping file deletion
Sentry.framework/_CodeSignature/CodeResources
rsync: mkstemp "<path/to/your/app>/Frameworks/Sentry.framework/_CodeSignature/.CodeResources.a2sA9v" failed: Operation not permitted (1)

sent 15034 bytes  received 42 bytes  30152.00 bytes/sec
total size is 4950281  speedup is 328.36
rsync error: some files could not be transferred (code 23) at /AppleInternal/Library/BuildRoots/5bb93434-bef0-11ef-bef2-d285688f7a47/Library/Caches/com.apple.xbs/Sources/rsync/rsync/main.c(996) [sender=2.6.9]
```

While it seems to be related to Sentry, it is actually caused by the user script sandbox feature introduced in [Xcode 14](https://developer.apple.com/documentation/xcode-release-notes/xcode-14-release-notes), which is enabled by default. In order to fix this, you need to head to the target settings of your project and set the "Enable User Script Sandbox" option to `NO`.

## ['required' initializer 'init(from:)' must be provided by subclass](#required-initializer-initfrom-must-be-provided-by-subclass)

Since Cocoa SDK version [8.45.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#8450) 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](https://github.com/getsentry/sentry-cocoa/issues/new/choose).

## [Unsymbolicated stacktraces for non fatal events](#unsymbolicated-stacktraces-for-non-fatal-events)

Cocoa SDK versions [8.51.1](https://github.com/getsentry/sentry-cocoa/releases/tag/8.51.1) and [8.52.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.52.0) have a bug that causes unsymbolicated stacktraces for non-fatal events, such as`captureError`, `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](https://github.com/getsentry/sentry-cocoa/releases/tag/8.52.1) or above or stay on version [8.51.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.51.0) or below to fix this problem.
