Skip to main content

Appium Troubleshooting

Most Appium tests that never start on TestingBot fail for one of three reasons: the capabilities do not match any device, the request waited in the queue longer than the Appium client was willing to wait, or the app reference no longer exists. This page explains each one and how to fix it.

For errors that happen after the session has started, such as idle timeouts, a lost device connection or WebDriverAgent no longer responding, see the test errors reference.

Find your error message

Message contains Section
TestingBot was unable to fulfill your request No matching device
Waited too long for job to start Queueing and client timeouts
A timeout raised by your Appium client while creating the session Client timeouts
Could not find stored object tb:// app not found
Please supply an URL or TestingBot Storage URI as app capability App capability is a local path
Please specify a deviceName Other start errors
Please specify either a browserName or app with deviceName Other start errors
Invalid platformName and automationName combination Other start errors
We currently do not support iOS version Other start errors

"Unable to fulfill your request": no matching device

TestingBot compares appium:deviceName, appium:platformVersion and platformName with the simulators, emulators and physical devices it offers. The rest of the message tells you what went wrong:

  • …is only available as a physical device, but your capabilities do not request one: the device exists only as real hardware, and your capabilities ask for a simulator or emulator, which is the default. Add "tb:options": { "realDevice": true }.
  • …is not available as a simulator/emulator, and no matching physical device is currently connected: the exact device name and version you sent match nothing at all. Check the spelling against the device list, leave out the version, or use a pattern (see below).
  • …most likely the device is currently in use or …please try again later: the request waited in the queue for 390 seconds and no matching device became free. A pattern that matches no device at all ends the same way, after the full wait.

The first two messages come back right away, without queueing, but only when you send an exact device name. A request with a pattern in deviceName or platformVersion is not checked up front: if the pattern matches nothing, the request waits in the queue until it times out. So when a test with a pattern sits in the queue for six minutes and then fails, check the pattern first.

The test errors reference has the full text of each message.

Physical devices and simulators are separate

Without realDevice, a request only matches iOS simulators and Android emulators, never a physical device, even when a physical device has exactly the name you sent. With "realDevice": true, it only matches physical devices. Pick one per test.

// physical iPhone 15 with any iOS 17 or 18 version
{
  "platformName": "iOS",
  "appium:deviceName": "iPhone 15",
  "appium:platformVersion": "17.*,18.*",
  "appium:app": "tb://<your-app-id>",
  "tb:options": { "realDevice": true }
}

Device name patterns

appium:deviceName can be an exact name or a pattern. TestingBot applies these rules (the full list is in the device name rules):

  • The pattern must match the whole device name. It is wrapped as ^(?:pattern)$, so "iPhone 15" does not match iPhone 15 Pro, and "Pixel" matches no device.
  • Case does not matter. "iphone 15" matches iPhone 15.
  • A comma separates alternatives, each matched against the whole name on its own.
  • [from-to] is a number range, so [14-16] means 14, 15 or 16.
appium:deviceName Device Matches?
"iPhone 15" iPhone 15 Pro No: the pattern must cover the whole name
"iPhone 15.*" iPhone 15, iPhone 15 Pro Yes
"iPhone 15 Pro" iPhone 15 Pro Max No
"iPhone 15 Pro, iPhone 16 Pro" iPhone 16 Pro Yes
"iPhone 1[4-6]" iPhone 15 Yes
"iPhone 1[4-6]" iPhone 17 No: outside the range
"iPhone 1[4-6].*" iPhone 16 Pro Max Yes
"Galaxy S2[3-5].*" Galaxy S24 Ultra Yes
"Pixel" Pixel 8 No
"Pixel.*" or "*" Pixel 8 Yes

Device names that contain parentheses, such as iPad (9th generation), need the parentheses escaped or skipped with .*. See the device name rules.

Version patterns

appium:platformVersion follows the same rules, with one extra: a plain major version also matches its minor versions.

appium:platformVersion Device version Matches?
"17" 17.5 Yes
"14" 14.0 Yes
"1[7-8]" 18.2 Yes
">=17" 18.2 Yes
"17,18" 18 Yes
"17,18" 18.2 No: with a comma, each alternative must match the whole version
"17.*,18.*" 18.2 Yes

To accept several major versions, write "17.*,18.*" or a range such as "1[7-8]", not "17,18".

Queueing and client timeouts

When your account is already running as many tests as your plan allows, or no matching device is free, a new session does not fail right away. It waits in a queue and starts as soon as a slot and a device are available. A request that has not started after 390 seconds fails:

  • Waited too long for job to start: you were at your plan's parallel limit for the whole wait. See concurrency limit reached.
  • TestingBot was unable to fulfill your request…: no matching device became free. See no matching device.

While it waits, your Appium client is still waiting for the answer to its new-session request. After the request leaves the queue, the device still has to install and launch your app before the session is returned.

Client timeouts

If the HTTP timeout of your Appium client is shorter than the queue wait plus the session start, the client gives up first. You then get a read timeout or connection error from the client library instead of TestingBot's message, which makes the real cause hard to see. Set the client timeout to at least 7 minutes; 10 minutes leaves room for a slow app install.

WebdriverIO waits 120 seconds for any WebDriver request by default. Raise connectionRetryTimeout (milliseconds) in wdio.conf.js or in the options you pass to remote():

export const config = {
  hostname: 'hub.testingbot.com',
  port: 443,
  protocol: 'https',
  path: '/wd/hub',
  connectionRetryTimeout: 600000, // 10 minutes
  // ...
};

The Appium Python client has a 120 second read timeout on each HTTP request. Raise it with the timeout argument (seconds) of AppiumClientConfig:

from appium import webdriver
from appium.options.common import AppiumOptions
from appium.webdriver.client_config import AppiumClientConfig

client_config = AppiumClientConfig(
    remote_server_addr="https://key:secret@hub.testingbot.com/wd/hub",
    timeout=600,  # 10 minutes
)
driver = webdriver.Remote(options=options, client_config=client_config)

For other clients, look for the HTTP read timeout of the client or its command executor. In the Java client, how it is set differs between major versions, so check the documentation of the version you use.

Queueing is usually a sign that more tests start at once than your plan runs in parallel. Lower the number of parallel workers in your test runner, or use a device name pattern so that any free device of a family can take the test instead of all tests waiting for one exact device.

tb:// app not found: "Could not find stored object"

When appium:app (or another capability) contains a tb:// reference, TestingBot looks up that upload in your account before the session is queued. If there is no such upload, the session fails right away with:

Could not find stored object <app id>

Common causes:

  • The upload has expired. Uploads to TestingBot Storage are deleted automatically after 60 days; see Upload Mobile App. A tb:// ID that is hard-coded in a test or a CI variable stops working once its upload is gone.
  • The upload was deleted in the dashboard or through the Storage API.
  • It was uploaded with another account's API key than the one your test uses to connect.
  • A typo in the ID. Copy the full app_url value returned by the upload.

The fix is the same in each case: upload the app again and use the tb:// ID from the new upload. The most reliable setup is to upload the build from your CI pipeline in the same job that runs the tests, so every run uses a fresh reference. See uploading your app.

App capability is a local path

Please supply an URL or TestingBot Storage URI as app capability. means the app value is neither an http(s):// URL nor a tb:// reference, usually because it is a path on your own machine. The device cannot read files on your computer: upload the file to TestingBot Storage first, or host it at a URL the device can download from.

When you use your own URL, TestingBot downloads the app while the device boots and retries a failed download. If it still fails, Appium tries the URL itself and the session fails with Appium's own error. Make sure the URL is reachable from the internet and does not require a login.

Other start errors

These messages are returned straight away, before the request is queued. Fix the capabilities and start the test again.

  • Please specify a deviceName: platformName is iOS, Android or tvOS but there is no appium:deviceName. Add one; a pattern such as "*" is fine. See Please specify a deviceName.
  • Please specify either a browserName or app with deviceName: the capabilities contain neither a browserName (mobile browser test) nor an app together with a deviceName (app test). Check that the capabilities actually reach TestingBot, for example that they are not nested under a key your client does not send.
  • Invalid platformName and automationName combination. iOS requires XCUITest: you asked for iOS with UiAutomator2. Use "appium:automationName": "XCUITest" for iOS and tvOS.
  • We currently do not support iOS version <version>, only <versions>: the iOS simulator version is not offered. Pick one of the versions listed in the message, or leave the version out.

For anything else, the test errors reference lists every message TestingBot returns, with its cause and fix.

Frequently asked questions

Why does my Appium test fail with "TestingBot was unable to fulfill your request"?

No simulator, emulator or physical device matches the capabilities you sent, or the matching physical device stayed busy. A common cause is a deviceName that does not describe the whole device name: "iPhone 15" does not match "iPhone 15 Pro". Use "iPhone 15.*" to match every iPhone 15 model, and add realDevice to tb:options when you want a physical device. See no matching device.

How long does an Appium session wait for a free device?

A new-session request that cannot start right away waits in the queue for up to 390 seconds before it fails. Set the HTTP timeout of your Appium client higher than that, otherwise the client gives up first. See queueing and client timeouts.

What does "Could not find stored object" mean?

The tb:// reference in your app capability no longer points to an upload in your account: the upload was deleted, it was deleted automatically after the storage retention period, or it was uploaded with another account's API key. Upload the app again and use the new tb:// ID. See tb:// app not found.

Was this page helpful?
Last updated