If your iOS Appium session dies with xcodebuild failed with code 65 (or Unable to launch WebDriverAgent because of xcodebuild failure), the number itself tells you very little. Code 65 is xcodebuild saying "the build or test run failed". The XCUITest driver builds and launches WebDriverAgent (WDA) on the device through xcodebuild, so any problem in that step comes back as the same code.
Short answer: on real devices, code 65 is almost always code signing. The Appium docs list it under provisioning issues: it "means that code signing is not set up correctly and must be reconfigured." On CI machines the usual variant is a keychain the build agent cannot read. Turn on appium:showXcodeLog to see the real error, then fix the cause from the list below.
Step 1: see the real error
By default Appium hides the xcodebuild output. Turn it on for one session:
{
"platformName": "iOS",
"appium:automationName": "XCUITest",
"appium:udid": "<device udid>",
"appium:showXcodeLog": true
}
Expect a lot of output. Scroll up from the code 65 line and look for the first real error. It usually mentions a development team, a provisioning profile, a certificate or the keychain.
If the log is still unclear, build WDA in Xcode yourself. Xcode's errors are easier to read:
appium driver run xcuitest open-wda
This opens the WebDriverAgent.xcodeproj that ships inside your installed driver and prints its path. Select the WebDriverAgentRunner scheme, choose your device under Product → Destination, and run Product → Test. If it fails here, Appium will fail too. Fix it here first.
Cause 1: WebDriverAgent is not signed for your team
WDA is an app that has to be installed on the device. Like any app, it needs a valid signing identity and a provisioning profile that matches its bundle id. By default the bundle id is com.facebook.WebDriverAgentRunner. That id belongs to nobody's team, so on a real device the build fails until you change it.
If you have a paid Apple Developer account, the simplest fix is to let xcodebuild handle signing. Pass your team and a bundle id your team can sign:
{
"appium:xcodeOrgId": "<your 10-character Team ID>",
"appium:xcodeSigningId": "Apple Development",
"appium:updatedWDABundleId": "com.yourcompany.WebDriverAgentRunner",
"appium:allowProvisioningDeviceRegistration": true
}
What each one does:
appium:xcodeOrgIdandappium:xcodeSigningIdwork as a pair. One without the other has no effect. If you leave out the signing id, it defaults toiPhone Developer. On current Xcode the identity is usuallyApple Development.appium:updatedWDABundleIdrenames WDA's bundle id before the build. The docs say it "must be associated with a valid provisioning profile".xcodebuildadds.xctrunnerto the end of the test runner's id, so your profile has to cover<your id>.xctrunner. A wildcard profile (com.yourcompany.*) covers it.appium:allowProvisioningDeviceRegistrationletsxcodebuildregister a new device on your developer account during the build. That is the usual cause of code 65 the first time you plug in a new phone.
Other signing problems that end in the same code:
- The profile expired or was revoked. The build worked last month and fails today with no changes on your side. Regenerate the profile, or let automatic signing do it.
- You use a free Apple Account. Free accounts can sign WDA with their personal team. But Appium's automatic configuration only works with paid accounts, so you have to set up signing in Xcode by hand. The first install also fails until you trust the certificate on the phone: open Settings → General → VPN & Device Management, select the Developer App entry for your Apple Account, and tap Trust. The phone needs an internet connection for this.
Cause 2: CI cannot read the signing key from the keychain
This one is easy to miss: the same machine builds WDA fine when you are logged in, and fails with code 65 when a CI agent runs it. The Appium docs explain it. A process started by a CI agent "does not have direct access to keychain", so code signing fails unless you prepare the keychain first.
The docs give two fixes. The first is to unlock the keychain before each build. It is the simplest to set up and the most reliable. Run it in the job before Appium starts:
security unlock-keychain -p "$KEYCHAIN_PASSWORD" ~/Library/Keychains/login.keychain-db
(fastlane's unlock_keychain does the same.)
The second is to put the signing key in its own keychain and point Appium at it:
security create-keychain -p "$KEYCHAIN_PASSWORD" MyKeychain.keychain
security import MyPrivateKey.p12 -t agg -k MyKeychain.keychain -P "$P12_PASSWORD" -A
{
"appium:keychainPath": "/Users/ci/Library/Keychains/MyKeychain.keychain-db",
"appium:keychainPassword": "<keychain password>"
}
Read both passwords from your CI secret store. Do not commit them to the repository.
Cause 3: the device is not ready for automation
A device in the wrong state also ends in code 65, even when signing is correct. Check these on the phone:
- Trust This Computer was accepted when you first connected the cable. An untrusted device does not show up as a run destination in Xcode.
- Developer Mode is on (iOS/iPadOS 16 and later): Settings → Privacy & Security → Developer Mode. The phone restarts to turn it on.
- Enable UI Automation is on: Settings → Developer → Enable UI Automation.
- The phone is unlocked and responsive. If it froze after a long run, restart it. The Appium docs give the same advice.
Cause 4: a stale build cache
If WDA built fine before and nothing in the list above changed, clear Xcode's derived data and try again:
rm -rf ~/Library/Developer/Xcode/DerivedData/*
This often helps after you upgrade Xcode or the XCUITest driver, because old WDA build products are still on disk. If you set appium:derivedDataPath, delete that folder instead.
A related error, code 70, can also come from signing. It is more often a bad xcodebuild configuration, such as a wrong platform version, or an Xcode too old to support the device's iOS version.
Stop rebuilding WDA on every run
Each fix above makes the build succeed. A better setup for CI is to not build WDA inside the test session at all. By default Appium runs xcodebuild build-for-testing and then test-without-building for every new WDA, so every session depends on signing working at that moment. You can build once and reuse the result instead.
Build once, then run from the .xctestrun file. From the WDA project folder (the path open-wda prints), this is the docs' simulator example:
xcodebuild build-for-testing \
-project WebDriverAgent.xcodeproj \
-derivedDataPath wda_build \
-scheme WebDriverAgentRunner \
-destination "platform=iOS Simulator,name=iPhone 14 Pro" \
CODE_SIGNING_ALLOWED=NO
Then tell Appium to use those build products instead of building:
{
"appium:useXctestrunFile": true,
"appium:bootstrapPath": "/path/to/wda_build/Build/Products"
}
For a real device, the build must be signed. Use a real device destination, drop CODE_SIGNING_ALLOWED=NO, and sign with your team and bundle id as in Cause 1. The build step needs the keychain unlocked, the same as in Cause 2. After that, test sessions do not touch signing at all.
On iOS 17 and later, use a preinstalled WDA. Install a signed WebDriverAgentRunner-Runner.app on the device once, then start sessions with appium:usePreinstalledWDA: true. Appium launches the installed app and does not run xcodebuild. The driver can also download prebuilt WDA packages (appium driver run xcuitest download-wda) and re-sign them (appium driver run xcuitest sign-wda).
If you already run WDA yourself, attach to it with appium:webDriverAgentUrl (for example http://localhost:8100 with a port forward). Appium then connects to that WDA and does not start a new one.
All three options take the most fragile step out of each test run. Signing problems then show up once, at build time, instead of failing random sessions overnight.
Checklist
- Turn on
appium:showXcodeLogand find the first real error abovecode 65. - Build WDA in Xcode (
open-wda→ Product → Test) to confirm it is not an Appium problem. - Set
xcodeOrgId,xcodeSigningIdandupdatedWDABundleId. Make sure your profile covers<id>.xctrunner. - On CI, unlock the keychain before the build, or use a dedicated keychain with
keychainPathandkeychainPassword. - On the phone, check Trust This Computer, Developer Mode, Enable UI Automation, and the trusted developer certificate.
- Clear derived data after Xcode or driver upgrades.
- Move the WDA build out of the test session: use an
.xctestrunfile, a preinstalled WDA, orwebDriverAgentUrl.
Sources
Checked against the Appium XCUITest driver documentation (driver 12.x docs) on 2026-10-25: