Upload dSYMs for iOS

Install posthog-cli:

npm install -g @posthog/cli

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/PostHog/posthog/releases/latest/download/posthog-cli-installer.sh | sh
posthog-cli-update

To authenticate the CLI, call the login command. This opens your browser where you select your organization, project, and API scopes to grant:

posthog-cli login

If you are using the CLI in a CI/CD environment such as GitHub Actions, you can set environment variables to authenticate:

You can also use the --host option instead of the POSTHOG_CLI_HOST environment variable to target a different PostHog instance or region. For EU users:

posthog-cli --host https://eu.posthog.com [CMD]

In Xcode, configure your build settings to generate dSYMs:

1. Open your project in Xcode
2. Select your target
3. Go to Build Settings
4. Search for Debug Information Format
5. Make sure Release configurations have DWARF with dSYM File

To symbolicate crash reports, PostHog needs your project's debug symbol (dSYM) files. The following script automatically processes and uploads dSYMs whenever you build your app.

Add a Run Script build phase:

1. In Xcode, select your main app target
2. Go to Build Phases tab
3. Click the + button and select New Run Script Phase
4. Make sure it's set to run last (after "Copy Bundle Resources" or similar)
5. Add the appropriate script for your package manager:

${BUILD_DIR%/Build/*}/SourcePackages/checkouts/posthog-ios/build-tools/upload-symbols.sh

${PODS_ROOT}/PostHog/build-tools/upload-symbols.sh

By default, only debug symbols are uploaded. To include source code snippets in your stack traces (for better debugging context), set the POSTHOG_INCLUDE_SOURCE environment variable:

1. In the Run Script build phase, click the chevron to expand
2. Set the environment Variable when calling the upload script:

POSTHOG_INCLUDE_SOURCE=1 ${BUILD_DIR%/Build/*}/SourcePackages/checkouts/posthog-ios/build-tools/upload-symbols.sh

POSTHOG_INCLUDE_SOURCE=1 ${PODS_ROOT}/PostHog/build-tools/upload-symbols.sh

Note: This increases upload size and build times. Only enable if you need source code context in PostHog's error tracking UI.

Build your app in Xcode. The dSYM upload script will automatically run and upload symbols to PostHog.

Check the build log output for confirmation.

To verify everything is working end-to-end, force a test crash and confirm it appears in PostHog.

1. Add a crash trigger button to your app:

Button("Test Crash") {
    fatalError("PostHog test crash")
}

let button = UIButton(type: .system)
button.setTitle("Test Crash", for: .normal)
button.addTarget(self, action: #selector(testCrash), for: .touchUpInside)
view.addSubview(button)

@objc func testCrash() {
    fatalError("PostHog test crash")
}

2. Build and run your app in Xcode,

   • Make sure the debugger is not attached, since it will intercept the crash and prevent the report from being collected. You can:
     • Detach the debugger (click the stop button in Xcode) and run the app directly from the device/simulator home screen
     • Or uncheck "Debug executable" in the scheme settings before running

3. Reopen the app from your device or simulator's home screen (not from Xcode).

4. Tap the Test Crash button. The app will crash. The exception is collected but not yet sent to PostHog.

5. Reopen the app once more. This triggers the SDK to send the previously collected crash report to PostHog.

6. Check the error tracking dashboard for your test crash.