When you try to run an app from Xcode on an iPhone, iPad, or Simulator, Xcode may display Could not launch and fail to start the app. This usually happens after the build stage, when Xcode attempts to launch or attach the debugger. Common causes include code signing, Developer Mode, device pairing, an existing installed app, scheme settings, debugger attachment, Simulator state, or stale build data.
- What does “Could not launch” mean?
- Common causes
- 1. Check the detailed error message
- 2. Check Developer Mode
- 3. Verify Signing & Capabilities
- 4. Remove an existing copy of the app
- 5. Check the Scheme and Run settings
- 6. Test whether the debugger is the problem
- 7. Check for an immediate crash
- 8. Reconnect and re-pair the device
- 9. Check Xcode and iOS compatibility
- 10. If the error occurs in Simulator
- 11. Clean the build and remove DerivedData
- Important caution
- Summary
What does “Could not launch” mean?
“Could not launch” is a general message indicating that Xcode could not start the target app process after building or installing it. The real cause is often shown in the more detailed message immediately before or after it, so the first step is to inspect the full Run log in the Report navigator or the device information in Devices and Simulators.
Example
Could not launch "AppName"This message by itself is not specific enough to identify the root cause. Look for additional details about signing, permissions, process launch, or debugger attachment.
Common causes
- Developer Mode is disabled
- Code signing or provisioning is incorrect
- The Mac and device are not properly paired or trusted
- An existing app with the same Bundle Identifier conflicts with the development build
- The wrong Scheme, target, or executable is selected
- LLDB cannot attach to the process
- The app crashes immediately after launch
- The Simulator is in an unstable state
- DerivedData or other build cache is stale
- The installed Xcode version does not fully support the device’s iOS version
1. Check the detailed error message
Open Xcode’s Report navigator and select the failed Run operation. Read the messages immediately before “Could not launch.” Signing errors, Developer Mode warnings, debugger errors, process errors, or permission failures usually provide a much more specific direction.
Because “Could not launch” can appear for many unrelated failures, avoid changing Build Settings at random. Use the detailed log to identify the actual failure first.
2. Check Developer Mode
Running development builds on supported iOS versions requires Developer Mode. On the iPhone or iPad, verify that Developer Mode is enabled. Enabling it may require restarting the device and confirming the setting after reboot.
3. Verify Signing & Capabilities
Open Target → Signing & Capabilities and review the Team, Bundle Identifier, Signing Certificate, and provisioning configuration. If you use automatic signing, make sure Automatically manage signing is configured correctly.
- Select the correct Apple Developer Team.
- Confirm the Bundle Identifier.
- Check for signing errors or warnings.
- Make sure the physical device is eligible for the development provisioning setup.
4. Remove an existing copy of the app
If the same Bundle Identifier is already installed with a different certificate or development team, the app may install or launch incorrectly. Delete the app from the device and run it again from Xcode.
5. Check the Scheme and Run settings
Choose Product → Scheme → Edit Scheme and inspect the Run configuration. Make sure the correct target and executable are selected. Projects with multiple targets can easily end up running the wrong Scheme.
6. Test whether the debugger is the problem
If the app can launch manually but fails only when started from Xcode, debugger attachment may be the issue. In Edit Scheme → Run → Info, check the Debug executable setting.
As a diagnostic step, temporarily disable Debug executable and see whether the app launches. This helps distinguish an app-launch problem from an LLDB attachment problem.
Disabling Debug executable prevents normal breakpoint debugging, so use it only for troubleshooting and restore the setting afterward.
7. Check for an immediate crash
Sometimes the app does launch but crashes almost immediately, which can make the failure appear to be a launch problem. Check the Debug navigator and console for crash logs, exceptions, or fatal errors.
Fatal error: Unexpectedly found nil while unwrapping an Optional valueIf you see a runtime error like this, fix the code executed during app startup.
8. Reconnect and re-pair the device
USB, wireless debugging, trust settings, and pairing issues can prevent launch or debugger attachment. Quit Xcode, disconnect the device, restart both the Mac and device, reconnect them, and then verify the device in Window → Devices and Simulators.
9. Check Xcode and iOS compatibility
If the iPhone or iPad is running an iOS version newer than the installed Xcode supports, installation may succeed while launch or debugging still fails. Confirm that your Xcode version supports the device’s iOS version and update Xcode when necessary.
10. If the error occurs in Simulator
If “Could not launch” occurs in Simulator, quit and restart the affected Simulator. If the problem persists, you can reset the Simulator with Device → Erase All Content and Settings.
You can also shut down all Simulators from Terminal:
xcrun simctl shutdown all11. Clean the build and remove DerivedData
If the configuration appears correct, stale build data may still interfere with launch. First run Product → Clean Build Folder. If that does not help, remove DerivedData.
rm -rf ~/Library/Developer/Xcode/DerivedData/*Restart Xcode and rebuild the project afterward.
Important caution
Avoid changing signing settings, EXCLUDED_ARCHS, or unrelated Build Settings without evidence from the detailed error. “Could not launch” is a broad message, so fixes should be based on the specific underlying failure.
Summary
Xcode’s “Could not launch” error means Xcode could not start or debug the app after the build stage. Begin with the detailed Run log, then check Developer Mode, signing, the existing installed app, Scheme settings, debugger attachment, device pairing, Xcode/iOS compatibility, and Simulator state.
If no configuration issue is obvious, restart the Mac and device or Simulator, clean the build folder, remove DerivedData, and try again.
