Unable to launch preinstalled WebDriverAgent on real iOS device (free Apple account)

[chetansutar008]

Issue Summary

I’m using a free Apple Developer account and built a custom WebDriverAgentRunner.ipa for real-device testing with Appium Device Farm.
Although the .ipa installs successfully on the iPhone and appears as verified, Appium fails to launch WDA when trying to start a session.

---

Steps to Reproduce

1. Built WebDriverAgentRunner-Runner.app using Xcode for my real device (with my Apple ID).

2. Zipped it manually into a Payload/ folder to create an .ipa.

3. Re-signed the IPA using the ipa-resign utility shared on the Appium Device Farm GitHub page (using my Apple free account provisioning profile).

4. Installed the IPA on the real iPhone — it installs and shows as verified under Settings → General → VPN & Device Management.

5. Configured Appium Device Farm to use the preinstalled WDA by passing the bundle ID capability:
   --plugin-device-farm-wda-bundle-id=com.chetans.WebDriverAgentRunner

6. Started a new session in Appium Device Farm.

---

Observed Behavior

Appium fails to launch WDA and throws the following error after 60 seconds:

Error: Unable to launch WebDriverAgent. Original error: Failed to start the preinstalled WebDriverAgent in 60000 ms. 
The WebDriverAgent might not be properly built or the device might be locked. 
Make sure the application com.chetans.WebDriverAgentRunner.xctrunner exists and it is launchable.

Full stack trace:

{
    "error": "unknown error",
    "message": "Error: Unable to launch WebDriverAgent. Original error: Failed to start the preinstalled WebDriverAgent in 60000 ms. The WebDriverAgent might not be properly built or the device might be locked. The 'appium:wdaLaunchTimeout' capability modifies the timeout.. Make sure the application com.chetans.WebDriverAgentRunner.xctrunner exists and it is launchable. https://appium.github.io/appium-xcuitest-driver/latest/preparation/real-device-config/ may help to complete the preparation.",
    "stacktrace": "UnknownError: Error: Unable to launch WebDriverAgent. Original error: Failed to start the preinstalled WebDriverAgent in 60000 ms. The WebDriverAgent might not be properly built or the device might be locked. The 'appium:wdaLaunchTimeout' capability modifies the timeout.. Make sure the application com.chetans.WebDriverAgentRunner.xctrunner exists and it is launchable. https://appium.github.io/appium-xcuitest-driver/latest/preparation/real-device-config/ may help to complete the preparation.\n at getResponseForW3CError (/opt/homebrew/lib/node_modules/appium/node_modules/@appium/base-driver/lib/protocol/errors.ts:1103:34)\n at asyncHandler (/opt/homebrew/lib/node_modules/appium/node_modules/@appium/base-driver/lib/protocol/protocol.ts:507:57)\nThe above error is caused by\nError: Error: Unable to launch WebDriverAgent. Original error: Failed to start the preinstalled WebDriverAgent in 60000 ms. The WebDriverAgent might not be properly built or the device might be locked. The 'appium:wdaLaunchTimeout' capability modifies the timeout.. Make sure the application com.chetans.WebDriverAgentRunner.xctrunner exists and it is launchable. https://appium.github.io/appium-xcuitest-driver/latest/preparation/real-device-config/ may help to complete the preparation.\n at bh.this (/Users/chetan.sutar/.appium/node_modules/appium-device-farm/lib/webpack:/appium-device-farm/lib/src/plugin.js:417:23)\n at bh.generator (/Users/chetan.sutar/.appium/node_modules/appium-device-farm/lib/webpack:/appium-device-farm/lib/src/plugin.js:403:17)\n at Generator.next (<anonymous>)\n at c4 (/Users/chetan.sutar/.appium/node_modules/appium-device-farm/lib/webpack:/appium-device-farm/lib/src/plugin.js:38:48)"
}

---

Expected Behavior

• WebDriverAgent should launch on the device and start the server at http://<device_ip>:8100 when triggered by Appium.

---

Environment

• macOS: [15.7.1]
• Xcode: [26.1]
• Appium: [3.1.0]
• Appium Device Farm Plugin: [device-farm@11.2.1]
• iOS Device: [iPhone 12 / iOS version 18.6.1]
• Apple Developer Account: Free (non-paid)
• WDA build type: Manually zipped .ipa from valid Xcode .app, re-signed using ipa-resign

---

Additional Notes

• The .ipa installs and verifies successfully on the device.
• Bundle ID used: com.chetans.WebDriverAgentRunner.
• The .xctest folder exists inside the .app bundle (PlugIns/WebDriverAgentRunner.xctest).
• The issue consistently reproduces on Appium Device Farm when trying to start WDA with the preinstalled IPA.

Would appreciate community input or confirmation if the WDA launch limitation is expected under free Apple Developer accounts, or if additional signing/entitlement adjustments are needed for Appium Device Farm to start the .xctrunner bundle successfully.

[chetansutar008]

CC @saikrishna321 could you please take a look when you get a chance? You had helped me earlier with a port restriction implementation, and I’d really appreciate your guidance on this one as well.

[chetansutar008]

Just to update I have already tried appium plugin run device-farm prepare-wda too.

[Mridul2110]

@chetansutar008 ARe you able to got this working?

[chetansutar008]

@Mridul2110 Yes , with prepare wda second command followed by resigning

appium plugin run device-farm prepare-wda --wda-project-path= --mobile-provisioning-file=

[silashayri]

Already, tested with this method also use a prebuilt wda and bundle ID in server-config.json but same issue connection refused issue but when try to use inspector or run tests with appium server no problem but only in adf can not run or use device because of econnect refused issue

[naspat-hub]

Issue Summary

I’m using a free Apple Developer account and built a custom WebDriverAgentRunner.ipa for real-device testing with Appium Device Farm. Although the .ipa installs successfully on the iPhone and appears as verified, Appium fails to launch WDA when trying to start a session.

Steps to Reproduce

1. Built WebDriverAgentRunner-Runner.app using Xcode for my real device (with my Apple ID).
2. Zipped it manually into a Payload/ folder to create an .ipa.
3. Re-signed the IPA using the ipa-resign utility shared on the Appium Device Farm GitHub page (using my Apple free account provisioning profile).
4. Installed the IPA on the real iPhone — it installs and shows as verified under Settings → General → VPN & Device Management.
5. Configured Appium Device Farm to use the preinstalled WDA by passing the bundle ID capability:
   --plugin-device-farm-wda-bundle-id=com.chetans.WebDriverAgentRunner
6. Started a new session in Appium Device Farm.

Observed Behavior

Appium fails to launch WDA and throws the following error after 60 seconds:

Error: Unable to launch WebDriverAgent. Original error: Failed to start the preinstalled WebDriverAgent in 60000 ms. 
The WebDriverAgent might not be properly built or the device might be locked. 
Make sure the application com.chetans.WebDriverAgentRunner.xctrunner exists and it is launchable.

Full stack trace:

{
    "error": "unknown error",
    "message": "Error: Unable to launch WebDriverAgent. Original error: Failed to start the preinstalled WebDriverAgent in 60000 ms. The WebDriverAgent might not be properly built or the device might be locked. The 'appium:wdaLaunchTimeout' capability modifies the timeout.. Make sure the application com.chetans.WebDriverAgentRunner.xctrunner exists and it is launchable. https://appium.github.io/appium-xcuitest-driver/latest/preparation/real-device-config/ may help to complete the preparation.",
    "stacktrace": "UnknownError: Error: Unable to launch WebDriverAgent. Original error: Failed to start the preinstalled WebDriverAgent in 60000 ms. The WebDriverAgent might not be properly built or the device might be locked. The 'appium:wdaLaunchTimeout' capability modifies the timeout.. Make sure the application com.chetans.WebDriverAgentRunner.xctrunner exists and it is launchable. https://appium.github.io/appium-xcuitest-driver/latest/preparation/real-device-config/ may help to complete the preparation.\n at getResponseForW3CError (/opt/homebrew/lib/node_modules/appium/node_modules/@appium/base-driver/lib/protocol/errors.ts:1103:34)\n at asyncHandler (/opt/homebrew/lib/node_modules/appium/node_modules/@appium/base-driver/lib/protocol/protocol.ts:507:57)\nThe above error is caused by\nError: Error: Unable to launch WebDriverAgent. Original error: Failed to start the preinstalled WebDriverAgent in 60000 ms. The WebDriverAgent might not be properly built or the device might be locked. The 'appium:wdaLaunchTimeout' capability modifies the timeout.. Make sure the application com.chetans.WebDriverAgentRunner.xctrunner exists and it is launchable. https://appium.github.io/appium-xcuitest-driver/latest/preparation/real-device-config/ may help to complete the preparation.\n at bh.this (/Users/chetan.sutar/.appium/node_modules/appium-device-farm/lib/webpack:/appium-device-farm/lib/src/plugin.js:417:23)\n at bh.generator (/Users/chetan.sutar/.appium/node_modules/appium-device-farm/lib/webpack:/appium-device-farm/lib/src/plugin.js:403:17)\n at Generator.next (<anonymous>)\n at c4 (/Users/chetan.sutar/.appium/node_modules/appium-device-farm/lib/webpack:/appium-device-farm/lib/src/plugin.js:38:48)"
}

Expected Behavior

• WebDriverAgent should launch on the device and start the server at http://<device_ip>:8100 when triggered by Appium.

Environment

• macOS: [15.7.1]
• Xcode: [26.1]
• Appium: [3.1.0]
• Appium Device Farm Plugin: [device-farm@11.2.1]
• iOS Device: [iPhone 12 / iOS version 18.6.1]
• Apple Developer Account: Free (non-paid)
• WDA build type: Manually zipped .ipa from valid Xcode .app, re-signed using ipa-resign

Additional Notes

• The .ipa installs and verifies successfully on the device.
• Bundle ID used: com.chetans.WebDriverAgentRunner.
• The .xctest folder exists inside the .app bundle (PlugIns/WebDriverAgentRunner.xctest).
• The issue consistently reproduces on Appium Device Farm when trying to start WDA with the preinstalled IPA.

Would appreciate community input or confirmation if the WDA launch limitation is expected under free Apple Developer accounts, or if additional signing/entitlement adjustments are needed for Appium Device Farm to start the .xctrunner bundle successfully.

Same issue was faced, during standalone app (wda-resign.ipa) execution. thru device-farm config json file for loading wda-resign.ipa loading iphone mirror screening in device-farm browser page.
If WebDriverAgentRunner is build and tested thru Xcode, it works good on iphone.
Simultaneously, encrypted binary wda-resign.ipa was build by following command:
appium plugin run device-farm prepare-wda --wda-project-path= --mobile-provisioning-file=
Log Result: It was prompting com.facebook.WebDriverAgentRunner - even after replacing new bundle id

[7b8a4bbd][DevCon Factory] Successfully requested the connection for 00008140-001C02E114DB801C:61467
[7b8a4bbd][XCUITestDriver@31e4] Starting WebDriverAgent initialization with the synchronization key 'XCUITestDriver'
[7b8a4bbd][XCUITestDriver@31e4] Trying to start WebDriverAgent once since at least one of webDriverAgentUrl,usePreinstalledWDA capabilities is provided
[7b8a4bbd][XCUITestDriver@31e4] Event 'wdaStartAttempted' logged at 1767810244600 (13:24:04 GMT-0500 (Eastern Standard Time))
[7b8a4bbd][XCUITestDriver@31e4] The bundle id 'com.facebook.WebDriverAgentRunner' did not exist
[7b8a4bbd][XCUITestDriver@31e4] Launching WebDriverAgent on the device without xcodebuild
[7b8a4bbd][XCUITestDriver@31e4] Event 'wdaStartFailed' logged at 1767810245149 (13:24:05 GMT-0500 (Eastern Standard Time))
[7b8a4bbd][XCUITestDriver@31e4] Error: '"xcrun" "devicectl" "device" "process" "launch" "--device" "00008140-001C02E114DB801C" "--terminate-existing" "--environment-variables" "{"USE_PORT":"61467","WDA_PRODUCT_BUNDLE_IDENTIFIER":"com.facebook.WebDriverAgentRunner","MJPEG_SERVER_PORT":"61466"}" "com.facebook.WebDriverAgentRunner"' failed. Original error: ERROR: The application failed to launch. (com.apple.dt.CoreDeviceError error 10002 (0x2712))
BundleIdentifier = com.facebook.WebDriverAgentRunner
NSLocalizedRecoverySuggestion = Provide a valid bundle identifier.
NSLocalizedFailureReason = The requested application com.facebook.WebDriverAgentRunner is not installed.
----------------------------------------
The operation couldn’t be completed. (OSStatus error -10814.) (NSOSStatusErrorDomain error -10814 (0xFFFFD5C2))
_LSLine = 1796
_LSFunction = runEvaluator

[7b8a4bbd][AppiumDriver@6a53] Event 'newSessionStarted' logged at 1767810245345 (13:24:05 GMT-0500 (Eastern Standard Time))
[7b8a4bbd][device-farm-/Users/naspat/.appium] 📱 Forwarding ios port to real device 00008140-001C02E114DB801C for manual interaction
[7b8a4bbd][DevCon Factory Device Farm] Requesting connection for device 00008140-001C02E114DB801C on local port 61466, device port 61466
[7b8a4bbd][DevCon Factory Device Farm] Cached connections count: 0
[7b8a4bbd][DevCon Factory Device Farm] Successfully requested the connection for 00008140-001C02E114DB801C:61466
[7b8a4bbd][device-farm-/Users/naspat/.appium] 📱 984969cf-f545-4ed1-a57e-ab91360b515f Session response: {"protocol":"W3C","error":{}}
[7b8a4bbd][device-farm-/Users/naspat/.appium] 📱 Removing pending session with capability_id: 984969cf-f545-4ed1-a57e-ab91360b515f
[7b8a4bbd][device-farm-/Users/naspat/.appium] 984969cf-f545-4ed1-a57e-ab91360b515f 📱 Device UDID 00008140-001C02E114DB801C unblocked. Reason: Failed to create session
[7b8a4bbd][AppiumDriver@6a53] Encountered internal error running command: Error: Error: Unable to launch WebDriverAgent. Original error: '"xcrun" "devicectl" "device" "process" "launch" "--device" "00008140-001C02E114DB801C" "--terminate-existing" "--environment-variables" "{"USE_PORT":"61467","WDA_PRODUCT_BUNDLE_IDENTIFIER":"com.facebook.WebDriverAgentRunner","MJPEG_SERVER_PORT":"61466"}" "com.facebook.WebDriverAgentRunner"' failed. Original error: ERROR: The application failed to launch. (com.apple.dt.CoreDeviceError error 10002 (0x2712))
BundleIdentifier = com.facebook.WebDriverAgentRunner
NSLocalizedRecoverySuggestion = Provide a valid bundle identifier.
NSLocalizedFailureReason = The requested application com.facebook.WebDriverAgentRunner is not installed.
----------------------------------------
The operation couldn’t be completed. (OSStatus error -10814.) (NSOSStatusErrorDomain error -10814 (0xFFFFD5C2))
_LSLine = 1796
_LSFunction = runEvaluator

Please help, need some input to fix and improve generating wda-resign.ipa method

[silashayri]

Hi,
Also after iOS 26 update I can't run or use device or even inspect the app in the device farm plugin. Just can do them with appium server not with the adf and in the adf got connection refused to port...
Any help or update? BTW update the all server and drivers and even the plugins to the latest versions.

[Mridul2110]

I can help you can ping me on linkedin so I understand the issue better.

[silashayri]

Actually, the issue is when using appium server itself withouth device farm plugin everything works well but when try to use device farm plugin and click use device in iOS phone got econnect refused. Also Aalready use iOS signer tool for wda resign ipa file and use the same wda which is used for appium server and also checked with the xCode for the. same bundleID.