Troubleshooting

Each heading is the message, or the symptom, you will see.

A feature works locally but not in the run

Push notifications don't arrive, a shared App Group is empty, iCloud does nothing, or a universal link opens Safari instead of your app.

Cause. These features need special entitlements, which aren't available in runs on our devices. This is expected, not a fault in your build.

Fix. Leave those tests out with skipTesting and test those features on your own devices.

"We couldn't prepare your app or test suite for our devices."

We couldn't get your app or Runner ready to install. Check that both are Development or Ad Hoc builds for a real device, not App Store builds, then retry.

The file is refused at upload

• "This file is not an .ipa: it has no app inside a Payload folder." — put the .app in a folder named Payload and zip that folder, as on Getting started.
• "This .ipa is a test suite (a -Runner.app)." — send the Runner as a .zip to /test-suite.
• "No test Runner app (a name ending in -Runner.app) was found in this .zip." — zip the <Target>-Runner.app from Build/Products/Debug-iphoneos/, not the .xctest on its own and not the app.
• "This file is not a valid zip archive." — the file is damaged, or has more than 65,535 files inside. Leave out what the app doesn't need and zip again.
• "This archive contains symbolic links, which are not supported." — zip with zip -qr (which follows links) rather than zip -y.
• "This bundle identifier is reserved and cannot be uploaded." — your app or Runner uses one of Apple's ids, or one of an app our devices keep. Give it its own bundle id.
• UNSUPPORTED_FILE_TYPE — the app's filename must end in .ipa, the suite's in .zip. Simulator builds, test plans and .xctestproducts are not accepted.
• 413 — the file is over 500 MB, the upload limit. 415 — send the file as a multipart upload (curl -F "file=@…").

"We couldn't install your app or test suite on the device."

Check that your app supports this device's iOS version — the deployment target in Xcode must not be newer than the device's iOS. Pick a newer device, or lower the deployment target.

"Your app or test suite uses a bundle identifier that our device already has installed."

Your app's or Runner's bundle id is the same as an app the device keeps, such as a browser. Give your app and its UI test target their own bundle ids, then retry.

"No iOS device matches: …"

400 UNKNOWN_DEVICE, listing every device we didn't recognise. Write devices as "<model>-<iOS version>", for example "iPhone 15-26", or just the model to take any iOS version. Copy names from the capability generator. Simulators are not available for XCUITest.

"All matching iOS devices are in use (…)"

Every matching device stayed busy for longer than maxQueueWaitSeconds. Retry, choose another model, leave the iOS version off, or raise maxQueueWaitSeconds.

"This device isn't ready to run XCUITest right now." / "No device host that can run XCUITest has a matching device right now."

The problem is on our side, not in your build. Retry in a few minutes, or pick another device.

"No tests matched the build's filters."

The run finished without a single test running, so the device is error. Check your filters:

• Entries are Target, Target/Class or Target/Class/method. Target is the test_target the suite upload returned, for example AcmeUITests — not the app's name.
• Every part must match your Swift names exactly.
• A skipTesting entry that covers every test leaves nothing to run.

A device ends timedout

• Past the limit. The run went past its runTimeout (or 120 minutes). Usually a test waiting for something that never appears, or a suite too long for one device. Raise runTimeout, split the suite across builds with onlyTesting, or fix the waiting test. The last finished test's video shows where it got to.
• No test started within 5 minutes. Something on the device, such as a system prompt, kept XCTest from starting. Retry the build; if it happens again, pick another device.

"The test run crashed on the device before it finished."

The test run stopped unexpectedly. Open the session's test output and device log (the Logs tab in the dashboard, or the session's links in the API) to see what happened last. If only your app crashed, you see something different: that test is failed, with the crash text as its message.

"The device disconnected during the test run."

We lost the device mid-run. This is on our side. Retry the build.

A build URL stopped working: "App farm://app-… was not found in your organization or has expired"

Uploads last 90 days, and when a library is full the oldest upload made through /xcuitest/v1 is replaced. Upload the file again and use the new URL. 400 APP_NO_BUNDLE_ID means the app was uploaded from the dashboard: upload the .ipa through POST /xcuitest/v1/app instead.

A test has no video

Clips appear only after the run has finished. A skipped test, a test cut off by a stop or timeout, or a very short test has no clip. A build sent with video: false has none at all.

The All Commands tab is empty, or missing steps

Rows are XCTest's own steps — taps, typing, waits, failed checks. Code that doesn't go through XCTest's UI APIs isn't listed, and in a very large suite later tests may have no rows. Their results and clips are not affected.