How to reliably debug PHBackgroundResourceUploadExtension during development?

Question

Created Mar ’26

Replies 2

Boosts 1

Participants 3

I'm developing a PHBackgroundResourceUploadExtension and finding it difficult to debug because the system controls when the extension launches.

Current experience:

The extension starts at unpredictable times (anywhere from 1 minute to several hours after photos are added)
By the time I attach the debugger, the upload may have already completed or failed
Breakpoints in init() or early lifecycle methods are often missed

Questions:

Is there a way to force-launch the extension during development (similar to how we can manually trigger Background App Refresh in Xcode)?
Are there any launch arguments or environment variables that put the extension in a debug/eager mode?

I tried taking photos/videos, but this doesn't trigged app extension in all cases.

Any tips for improving the debug cycle would be greatly appreciated.

Environment: iOS 26, Xcode 18

Answered by Engineer in 892789022

Available in iOS 27, there is a setting to assist developing your extension. Look in Settings -> Developer -> Resource Upload Test Mode. When this setting is enabled, it relaxes some of the restrictions that may have hindered your development (for instance, debugging your extension should be much more manageable). That stated, there are some requirements for this setting to take effect:

Your Xcode project will need to be setup with an Apple Developer account
It will also need a Provisioning Profile
The setting is only applicable to binaries deployed directly by Xcode.

Once your debugging is completed, be sure to further your testing with the setting disabled. This is required to ensure your extension is operational under the same conditions your customers will be experiencing (for instance, your extension has a limited time to complete its tasks. If it is suspended due to a timeout, that will contribute to delays as to when the system will contact the extension again).

Please continue to refer to Uploading asset resources in the background on how to setup your PHBackgroundResourceUploadExtension. This reference will continue to be updated with the latest API changes and best practices.

As always we appreciate your feedback. If you have any suggestions or recommendations please file a feedback report.

Answer 1

mxrider108 OP

Mar ’26

Agreed this would make things much easier to test, especially given how sparse the docs are on this topic.

Answer 2

Engineer OP

Apple

5d

Recommended

Available in iOS 27, there is a setting to assist developing your extension. Look in Settings -> Developer -> Resource Upload Test Mode. When this setting is enabled, it relaxes some of the restrictions that may have hindered your development (for instance, debugging your extension should be much more manageable). That stated, there are some requirements for this setting to take effect:

Your Xcode project will need to be setup with an Apple Developer account
It will also need a Provisioning Profile
The setting is only applicable to binaries deployed directly by Xcode.

Once your debugging is completed, be sure to further your testing with the setting disabled. This is required to ensure your extension is operational under the same conditions your customers will be experiencing (for instance, your extension has a limited time to complete its tasks. If it is suspended due to a timeout, that will contribute to delays as to when the system will contact the extension again).

Please continue to refer to Uploading asset resources in the background on how to setup your PHBackgroundResourceUploadExtension. This reference will continue to be updated with the latest API changes and best practices.

As always we appreciate your feedback. If you have any suggestions or recommendations please file a feedback report.