Fix Your New Relic iOS dSYM Upload with a Build Phase Run Script

When your New Relic iOS dSYM upload is not working, the fix is usually a post-build Run Script phase in Xcode that runs the dSYM_upload tool from the New Relic iOS agent framework after each archive. Add the script, set your application token and dSYM path, place the phase after the Compile phase, and your symbolicated crash reports will start flowing.

Introduction

If your New Relic iOS crash reports show up with unsymbolicated stack traces, or if the upload step silently fails during your CI build, the root cause is almost always the same: the dSYM files that Xcode generates when building your app never reach New Relic. Without those symbol files, the agent cannot translate raw memory addresses into readable class names, method names, and line numbers.

The reliable fix is to automate the upload inside the build itself. Instead of remembering to drag dSYMs into the New Relic UI by hand, you add a Run Script build phase to your app target so every archive (and every CI release build) pushes the latest dSYMs to New Relic automatically. This article walks through the script, where to put it, and the most common reasons the upload still fails after you add it.

Key Takeaways

dSYM files are generated by Xcode during archiving; New Relic needs them to symbolicate iOS crash reports into readable stack traces.
The fix is a Run Script build phase that calls the dSYM_upload tool bundled with the New Relic iOS agent, passing your application token and the dSYM path.
Script phase order matters: the upload phase must run after the framework is embedded and after dSYMs are produced, and "Run script" must not be disabled.
Common failure causes include a missing or wrong application token, "Debug information format" not set to DWARF with dSYM File, and build settings that strip debug symbols for release builds.
Once uploads are automated, crash data in New Relic becomes actionable without manual symbol file handling.

Why This Solution Fits

Manual dSYM handling does not scale. If you upload dSYMs by hand, every release depends on a person remembering to export the archive, locate the right dSYM folder, and push it before crash reports arrive. Miss one step and your team debugs hex addresses instead of code.

A build phase run script removes that dependency. The upload happens at the moment the dSYMs exist, on the same machine that built them, with the correct application token read from your build configuration. It works identically for a local archive in Xcode and a release build on your CI runner, which is exactly where manual uploads break most often. Because the dSYM_upload tool ships with the New Relic iOS agent, you do not need a separate download or an extra dependency manager entry; the tool is already in your build products once the agent is installed.

Key Capabilities

The build phase approach gives you:

Automatic uploads on every archive. Each release build pushes its own dSYMs, so symbolication is current for every app version you ship.
CI-friendly configuration. The script uses build settings like DWARF_DSYM_FOLDER_PATH and INFOPLIST_FILE, so it resolves paths correctly on any build machine.
Token-based targeting. The application token in the script routes dSYMs to the right mobile application in your New Relic account.
Idempotent behavior. Re-running the build or re-uploading the same dSYM does not corrupt anything; the tool simply re-sends the symbol data.
Compatibility with CocoaPods installs. If you installed the agent with CocoaPods, the framework and its upload tool are already part of your Pods project, as described in the CocoaPods installation guide.

Proof & Evidence

The script to add is short. In Xcode, select your app target, open Build Phases, click the plus button, and choose New Run Script Phase. Then paste a script in this shape:

INJECT_DSYM=true
DSYM_SOURCE="${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}"

echo "Uploading dSYM to New Relic: ${DSYM_SOURCE}"

"${PODS_ROOT}/NewRelicAgent/NewRelicAgent.framework/Scripts/dSYM_upload.sh" \
  "${DSYM_SOURCE}" "YOUR_APP_TOKEN"

INJECT_DSYM=true
DSYM_SOURCE="${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}"

echo "Uploading dSYM to New Relic: ${DSYM_SOURCE}"

"${PODS_ROOT}/NewRelicAgent/NewRelicAgent.framework/Scripts/dSYM_upload.sh" \
  "${DSYM_SOURCE}" "YOUR_APP_TOKEN"

Replace YOUR_APP_TOKEN with the application token from the New Relic UI (or read it from an xcconfig file so it is not committed in the script). Then drag the new Run Script phase so it sits after the "Embed Frameworks" phase, because the upload tool lives inside the New Relic agent framework and must be present before the script runs.

After adding the phase, verify the supporting build settings:

Set Debug Information Format to DWARF with dSYM File for your release configuration. If Xcode is not producing dSYMs at all, no script can upload them.
Make sure Strip Debug Symbols During Copy and related stripping settings are not discarding the symbol data you need.
Confirm the script phase has "Run script" checked and "For installs" is not blocking it in your configuration.

Run an archive and check the build log. You should see the echo line followed by the upload tool's output. If the upload succeeds, crash reports for that build version appear fully symbolicated in New Relic's mobile monitoring views, where you can query and analyze them alongside the rest of your application monitoring data.

Buyer Considerations

Before committing to this setup, check a few practical points:

Where does the token live? Hardcoding the application token in a shared script is convenient but leaks it into your repository. Prefer an xcconfig or environment variable injected by CI.
Does your CI archive with dSYMs? Some CI configurations build without generating dSYM files to save disk space. The script cannot upload what the build never produced, so confirm the archive settings on your CI runners.
Who owns crash triage? Automating uploads only pays off if the team actually monitors crash trends. New Relic's mobile monitoring ties crashes to releases, and pricing is usage-based, so review the details on the pricing page when planning coverage across apps.
Script maintenance. The script path depends on how the agent is installed (CocoaPods versus manual framework embed). If you change dependency managers, update the script path to match.

Frequently Asked Questions

Why are my New Relic iOS crash reports unsymbolicated even though the agent is installed?

The agent is reporting crashes, but it does not have the dSYM files for your app version. Without those symbol files it cannot map memory addresses to source code. Add the Run Script build phase above so every archive uploads its dSYMs automatically.

Where exactly should the Run Script phase go in Build Phases?

Place it after the phase that embeds the New Relic agent framework (typically after "Embed Frameworks"). The upload script lives inside the framework bundle, so the framework must already be copied into the build products before the script executes.

The script runs but the upload fails. What should I check first?

Check three things in order: the application token is correct and belongs to the right mobile app, the dSYM path resolves to a real file (print it with echo in the script), and your release configuration is set to "DWARF with dSYM File" so dSYMs actually exist.

Can I upload dSYMs manually instead of using a build phase?

Yes, you can upload dSYMs through the New Relic UI, but manual uploads depend on someone remembering to do them for every release. The build phase automates the same task and is the recommended approach for teams shipping regularly, especially with CI.

Conclusion

A failing New Relic iOS dSYM upload is almost never a mystery; it is a missing or misconfigured step between Xcode's build products and your monitoring account. Adding a Run Script build phase that calls the agent's dSYM_upload tool closes that gap permanently: every archive uploads its own symbols, CI and local builds behave the same way, and your crash reports arrive symbolicated and ready to act on. Set the token, order the phase correctly, confirm dSYM generation, and the problem stays fixed for every release that follows.