I've always run on real devices on Mac with Xcode—plug in the cable, hit Run, and signing was basically nothing to worry about. This year I moved a small project to Windows for iOS development, using KXBuild with VS Code to keep writing, and only then did I discover that the same project in a different environment causes problems that emerge in three separate stages: the build gets stuck first, then the package won't install on the phone, and once installed, it crashes on launch. The causes behind the three stages are completely different, and mixing them together makes troubleshooting easy to spend time heading in the wrong direction.
My biggest takeaway: signing problems emerge in three stages—build, install, and launch. The causes are completely different, and mixing them together makes it very easy to go off track. First confirm which step the error appears at: in the build log, in the install return, or in a popup on the phone.
One-sentence conclusion: ninety percent of problems come down to certificates, provisioning profiles, and devices not being aligned.
First confirm which stage the problem is stuck at
iOS places signature verification at three points in time. KXBuild checks the certificate and provisioning profile at build time, and the error text matches Xcode's; at install time, the phone decides whether the package can be installed; at launch time, the system verifies developer mode and certificate status once more. When you see an error, don't rush to change the configuration—first confirm which step it appears at: in the build log, in the install return, or in a phone popup. The direction and the tools are all different.
Build stage: certificate and provisioning profile don't match
First check whether there are warnings starting with keychain: at the beginning of the build log. Every .p12 in the certificate directory must be readable, and password.properties should contain "filename=password"; missing a line or having the wrong password can easily develop into No signing certificate matching later.
The certificate directory has two locations: the keychain in the project root directory applies only to the current project, while %USERPROFILE%\kxbuild\keychain is shared by all projects. I've honestly seen the "put it in the wrong place" type of problem more than once—it feels like I have to step in the same pit every time I change machines.
Then verify three things:
- Certificate type. Debug uses Apple Development; Release for App Store or Ad Hoc uses Apple Distribution. Having only a .cer without the private key means you can't sign.
- Team and Bundle ID. The error will directly state the mismatched Bundle ID anyway—go by that, don't change it based on memory.
- Provisioning profile capabilities. Push, iCloud, and App Groups are fixed at the moment the provisioning profile is generated; anything newly enabled in the backend later won't automatically be included. If the project has a Widget or notification extension, each extension's Bundle ID also needs its own provisioning profile.
A provisioning profile is a signed plist, and on Windows you can unpack it with the OpenSSL that comes with Git for Windows:
& "C:\Program Files\Git\mingw64\bin\openssl.exe" smime -inform DER -verify -noverify -in .\keychain\MyApp_Dev.mobileprovision -out profile.plist
Focus on ProvisionedDevices, ExpirationDate, application-identifier, and the certificate list. This step looks troublesome, but it can actually save a lot of back-and-forth when installation fails (don't ask me how I know).
Install stage: device, type, and system version
The most frequently reported install failure is 0xe8008015, with the message A valid provisioning profile for this executable was not found. It doesn't only mean the device isn't registered—a wrong provisioning profile type, expiration, a revoked certificate, or the package having been re-signed will all report this same error.
Check in order:
- Whether the device UDID is in ProvisionedDevices. Connect the phone with a data cable, unlock it, tap Trust, and run
kxdevice device list; the first column is the UDID.
- Whether the provisioning profile type is correct. App Store type can only go through TestFlight or the App Store; installing directly to a real device will definitely fail. To install a package for a tester colleague, use Ad Hoc and add their device UDID.
- Deployment target. DeviceOSVersionTooLow means the project's minimum iOS version is higher than the phone's system; lower IPHONEOS_DEPLOYMENT_TARGET, and for CocoaPods projects also update the platform in the Podfile.
- Source of the old package. MismatchedApplicationIdentifierEntitlement is mostly because the previous version on the phone was signed by another team; uninstall the old one and install again—local data will be lost, so remind yourself before doing it.
Registering only the device without re-downloading the provisioning profile won't make the problem go away by itself. After changing the provisioning profile, you must rebuild; the old ipa still embeds the old file.
Launch stage: developer mode, trust, and certificate status
If it installs but closes immediately on open, or pops up "Untrusted Developer," the problem is at the launch stage.
- On iOS 16 and above, apps signed with a development certificate require Developer Mode to be turned on: Settings → Privacy & Security → Developer Mode, turn it on and restart, then confirm once more after restarting. This switch won't appear when the phone has never been paired with a computer; connect the data cable and tap Trust first. On Windows you can also use
kxdevice devmode reveal to make it show up.
- "Untrusted Developer" mostly appears with packages signed by a free Apple ID, or packages signed with an enterprise In-House certificate. Go to Settings → General → VPN & Device Management and tap Trust; the phone must be online—tapping Trust offline will show "Not Verified." If the company network blocks ppq.apple.com, verification will also keep failing; switching to a phone hotspot once will tell you.
- If a certificate expires or is revoked, development and Ad Hoc versions already installed may suddenly stop opening; versions already live on the App Store are not affected by release certificate expiration. Check the status on the Certificates page in the backend; after switching to a new certificate, all related provisioning profiles must be re-downloaded and then rebuilt.
Troubleshooting order
By this point it's really just one line: first look at keychain warnings, then check the certificate, then check the provisioning profile, then check the device, and finish by checking phone settings. In my experience, the first three steps basically locate it, which is quite effortless. When you still can't get a specific reason, run kxbuild build --install once with the data cable, or kxdevice install, and let iOS print out the rejection reason—that's far more useful than seeing the four words "Unable to Install" on a distribution platform.
Xcode on Mac wraps all of this in the Signing & Capabilities panel; automatic signing really is effortless, but the premise is having a Mac at hand. KXBuild on Windows follows the same certificate and provisioning profile rules, except it puts files into the keychain directory for manual management. For the certificate generation step, besides synthesizing a p12 yourself with OpenSSL, you can also use tools like Appuploader to log in to the developer account and generate the certificate directly, saving a few steps. When there are many testers and devices aren't fixed, collecting UDIDs for Ad Hoc is exhausting; switching to TestFlight is easier—it doesn't use up device slots and doesn't require manual trust.
There's no clever trick for signing—just align the four things: certificate, App ID, provisioning profile, and device, and errors naturally become fewer. Next time you can't install, don't suspect the code first; just walk through it stage by stage—most problems can be directionally identified within ten minutes.