1. Docs
  2. Resources
  3. Agent Pool & Device Farm
  4. Troubleshooting

Troubleshooting

Find the message or symptom you see. Each entry says why it happens, what to check and how to fix it.

15 min read Updated CustomersAdmins

In short

On this page you can

  • Fix an agent that stays Offline or has no live performance.
  • Get Appium, the emulator, Connected Devices and Windows or Mac desktop setups working.
  • Solve live device problems: “Connection failed”, a device that cannot be taken.
  • Recover nodes and devices that are Offline or stuck Busy.
  • Fix App Library uploads and installs, and access messages.

How to use it

  1. Search this page for the exact message you see (Ctrl+F).
  2. Open the entry and read Why first.
  3. Work through Check in order; most problems end there.
  4. Apply Fix; if it persists, write to info@smartestqa.ai with the time and the agent or device name.

Some messages from the server are shown exactly as the server sends them. A few of these appear in Turkish in some versions; they are listed below with their meaning.

Test agents#

The agent stays grey (Offline)Agent
Why
The client is not running, the computer slept, it uses another agent’s key, or a proxy blocks its connection.
Fix
The full checklist is in Quick Start › agent offline. The rule behind the dot: When is an agent Online?
“No agents found”Agent
Why
The list could not be loaded, or your session expired. Every user normally sees at least Smartest Server and their Localhost agent.
Fix
Reload the page. If it stays empty, sign out and in again. Still empty: write to info@smartestqa.ai.
“An agent with this name already exists. Please try a different name”Agent
Why
Agent names are unique within your company, including agents created by colleagues.
Fix
Pick a more specific name, such as the machine name plus its purpose (build-02-android). See Create a shared agent.
“Failed to create agent.” / “Failed to update agent name.”Agent
Why
The server rejected the request: an empty name, an expired session or a network problem.
Fix
Check the name is not empty, reload the page and try again.
“Local agent names cannot be updated” / “Local agents cannot be deleted” / “You are not authorized to delete this agent. Only Admin or the creator can delete it.”Agent
Why
Your Localhost agent belongs to your user account and is permanent. Only agents under Virtual Machine List can be renamed or deleted. Smartest Server cannot be changed at all.
Check
That you selected an agent under Virtual Machine List.
Fix
To stop using your Localhost agent, close the client. If the authorization message appears for a shared agent, ask an admin or the person who created it. See Delete a shared agent.
“Failed to delete agent. Please try again.”Agent
Why
The agent was already deleted by someone else, belongs to another company, or the request failed.
Fix
Reload the page. If the agent is still listed, try again.
The Install Via CLI command failsAgent
Check
  1. Windows: you run it in PowerShell, not Command Prompt; curl.exe exists (Windows 10 and 11 include it).
  2. Linux: curl and unzip are installed.
  3. The machine can reach the download address and SmartestQA; a proxy may block one of them.
  4. You copied the command after selecting the right agent, so it carries that agent’s key.
Fix
Install the missing tool, or download the zip with Download Client, unpack it and start the client with the key. 7-Zip is not needed.
“This agent is offline. Live performance appears when it connects.” / “The agent is not reporting performance metrics for this host yet (is it online?).” / “Couldn't reach the agent. Make sure the host is online and try again.”Agent
Why
Live performance needs a connected agent that sends metrics. An offline agent is not asked; a just-started or older client may not send metrics yet.
Fix
Start the agent and wait for Online. If the agent is online and the message stays, update the client with Download Client.
“Select a host to see the command with your API key.”MCP
Fix
Select an agent in the list (your Localhost agent is fine). The MCP commands then include its key.

Appium and local devices#

“Appium server not found” / “Appium off” / “Appium not running”Setup
Why
The agent asked Appium on localhost:4723 and got no answer. Mobile tests and live sessions on your agent need it.
Check
  1. A terminal with appium is still open on the agent computer.
  2. Nothing else uses port 4723.
  3. Hover the Appium chip for the address and error it reports.
Fix
Open a new terminal and run appium; leave it open. Then click Refresh in Connected Devices.
A test fails with “Server Unreachable / ECONNREFUSED 127.0.0.1:4723”Setup
Why
The terminal running Appium was closed, so nothing listens on port 4723.
Fix
Run appium in a new terminal and keep it open while tests run. See Android emulator.
Installing Appium fails with ERR_REQUIRE_ESMSetup
Why
The installed Node.js is too old for the current Appium. The guide may still mention an older minimum version.
Fix
Install the current Node.js LTS version, open a new terminal, check with node -v and run the Appium command again.
adb devices lists the emulator as offline, or not at allSetup
Check
  1. The emulator has finished starting and shows its home screen.
  2. Android SDK Platform-Tools is installed (step 2 of the guide).
  3. For a phone: USB debugging is on and you accepted the prompt on the phone.
Fix
Wait for the emulator, then run adb devices again. If it stays offline, close and restart the emulator from Device Manager.
“No Android devices found” / “No iOS devices found (macOS agent required)”Setup
Why
The agent sees no device of the project’s platform. iOS devices and simulators can only be reached by an agent on a Mac.
Fix
Start the emulator or connect the phone, check adb devices, then click Refresh. For iOS, run the agent on macOS. See Local device setup.
A desktop test stops with “session terminated / driver unreachable”Setup
Why
On Windows: Developer Mode is off, so WinAppDriver crashes during the session.
Fix
Turn on Developer Mode in Settings › Privacy & Security › For developers, restart if asked, and start Appium again. See Windows machine for desktop tests. Recording problems: Discover › desktop agent.
“Xcode is missing or not selected (macOS)”Setup
Why
The Mac2 driver that runs macOS desktop tests needs the full Xcode. Xcode is not installed, has never been opened, or only the Command Line Tools are selected.
Check
xcode-select -p should print /Applications/Xcode.app/Contents/Developer; appium driver doctor mac2 lists what is missing.
Fix
Install Xcode 13 or newer from the App Store and open it once, then run sudo xcode-select -s /Applications/Xcode.app/Contents/Developer. If the driver is missing too, run appium driver install --source=npm appium-mac2-driver. See Mac for desktop tests.
“A macOS permission is missing”Setup
Why
macOS has not allowed the agent or Xcode Helper to control the app, or the Desktop Recorder to capture the screen and your input.
Check
In System Settings › Privacy & Security: Accessibility lists Xcode Helper and the app that runs the agent (SmartTest-Desktop, or Terminal); for recording, Screen Recording and Input Monitoring list that app too.
Fix
Add the missing entries, run automationmodetool enable-automationmode-without-authentication once, restart the agent and try again. See Mac for desktop tests.

Live device sessions#

“Connection failed” / “Could not start stream” / “Reconnecting… (n/3)” does not endLive
Why
The device did not start streaming in time: it is busy with a running test, the node or agent is unreachable, or the first start on a device takes long (the tools are copied to it once).
Check
  1. The device is Available (farm) or listed under Connected Devices (agent).
  2. The node or agent is Online.
  3. For devices on your agent: Appium is running.
Fix
Click Try Again. The second start is faster. If it keeps failing, restart the device (admins) and try again. Timings: Live session timings.
The device cannot be taken: “This device is not available to your company.”, a Turkish message about an active reservation, or about the device not being free (status=BUSY)Live
Why
Live control is allowed only on a device that is free and that your company may drive. In the cloud service that means devices assigned to your company; shared devices need a reservation, which is not offered in the app, so they are used by runs only. The Turkish messages are “Cihazı canlı sürmek için aktif bir rezervasyonunuz olmalı” (you need an active reservation) and “Cihaz canlı izleme için müsait değil” (the device is not free).
Fix
Pick an Available device assigned to your company. If you need a dedicated device, ask via the Device Farm request or info@smartestqa.ai. See Rules that apply.
I can see an iOS device but clicks do nothing: “iOS control will be active in Phase 4 (Mac agent required).”Live
Why
Live control of iOS devices is not available yet; you can watch the screen only.
Fix
Use the live view to watch, and run iOS interactions as tests. Android devices support full control.
“This codec is not supported yet (will be added in Phase 3).”Live
Why
The device offered a stream format this browser view cannot play.
Fix
Update the agent or node client and try again in a current Chrome or Edge. If it persists, send the device name and time to info@smartestqa.ai.
A device stays Busy, or shows “no active session found — the device is probably stuck”Device
Why
A live session or run ended without releasing the device, for example after a browser crash.
Check
The holder line in Device details: who or what holds it.
Fix
Wait up to about 3 minutes: a live session lease expires by itself, and a run stuck for 120 minutes is closed automatically. Admins can use Force release at once (“Force-release the session?”).

Nodes and devices#

“No devices belong to this company” / “No visible devices”Device
Why
No device is visible to you. Admins and on-premise users see devices on your company’s nodes, so the list is empty until a node of yours reports devices. Cloud users see the devices assigned to or shared with your company.
Fix
Admins: add a node and connect devices to it. Users: ask your admin, or info@smartestqa.ai if your company should have farm devices.
“No devices match your filters.” / “No results”Device
Fix
Click Clear all in the filter panel and remove tag filters. Filters are remembered in your browser, so old ones may still apply. See Find a device.
A node is Offline, or its devices show “Node offline”Node
Why
The node stopped sending heartbeats: the computer is off or asleep, the client stopped, or the network is down. See When a node goes Offline.
Check
  1. The node computer is on and the client runs with the node’s key.
  2. Last Heartbeat in Nodes.
  3. The computer can reach SmartestQA.
Fix
Start the client again (re-run the command from Copy install command). The node and its devices come back Online by themselves. Runs that were active when it went down are closed as Failed; run them again.
Health shows “Check · Appium”, “Check · API” or “Check · CDN”Node
Why
The node is online but one of its services does not answer: Appium (devices cannot be driven), the SmartestQA API, or the file server that delivers app builds (installs fail).
Fix
Admins: open Node view and start or restart Appium there, or use Restart node agent. For API or CDN, check the node’s network and proxy.
“A node named “…” already exists in this company. Please choose a different name.” / “Node name is required”Node
Fix
Enter a name that no other node of your company uses. The field turns red while you type a duplicate. See Add a node.
“Failed to create node” / “Could not fetch API key” / “Could not delete node” / “Command could not be sent” / “Select a node first”Node
Why
The request failed, you are not an admin, or no node was ticked for a menu action.
Fix
Tick the node first, reload the page and try again. Node actions need the Admin role (Who can do what).
Wi-Fi and airplane mode are locked on a deviceDevice
Why
The device provides the node’s internet through USB tethering, or it is connected over wireless ADB. Turning the network off would cut the node or the device off, and it could not be restored remotely.
Fix
Connect the device by USB and give the node its own network, then the switches unlock. Mobile data is not locked by tethering.
“Device is not reachable” / “Device is offline” / “No baseline saved for this device yet”Device
Why
Restart and network switches need an online device. Reset to baseline needs a saved baseline. Busy devices block restart and baseline actions.
Fix
Wait until the device is Available. Save a baseline first with Set as baseline. See Controls.
“Live logcat is not available for iOS devices (Android only).” / “Waiting for device logs…” / “No recent logcat output from this device.”Device
Fix
Device logs are for Android devices that are online. Wait a few seconds after opening the device; an idle device may have no recent output.
“No eligible devices” / “Bulk action failed” / “could not send install command”Device
Why
No selected device was online and of the app’s platform, or the command could not be queued.
Fix
Select online devices of the right platform (others are marked “wrong platform”) and try again. See Install on devices.
Install shows “timed out — no result from the device” or “Finished with errors”Device
Why
The node did not report a result within 6 minutes, or the install failed on the device (no space, wrong build, node cannot download the file).
Check
The node’s Health (CDN must be up), the device’s free disk, and that the app’s platform matches the device.
Fix
Click Retry failed. For a build of the wrong type (for example an .ipa for a simulator), upload the right file.
“No runs yet” / “No runs match these filters.”Runs
Why
No test has run on a farm device yet, or your filters hide them. Runs on your own agent are not farm runs and do not appear here. Cloud users see only runs of projects they can open.
Fix
Click Clear all. Run a test on the Device Farm from Automate or Schedule.
“No telemetry for this run”Runs
Why
Metrics are collected only for Android runs, and the node client must be up to date. Emulators have no temperature or battery sensor (“Emulator — no sensor”).
Fix
Admins: check the node’s Agent column for “Update available” and update it.

App Library#

“Only APK, AAB, IPA or simulator .zip files can be uploaded.”App Library
Fix
Upload an .apk, .aab, .ipa, or a .zip of an iOS simulator .app folder. See Upload a build.
“App Library is full — update an existing app or delete one to add a new app.”App Library
Why
Your company has 30 apps, the limit.
Fix
Use Replace app for new builds instead of adding them again, and delete apps you no longer test.
“package id could not be read” / “n app(s) missing package id” / “App details (package/activity) could not be read”App Library
Why
SmartestQA could not read the package id or bundle ID from the file, often because the platform was detected wrong. Runs with such an app may open the wrong app.
Fix
Admins: open App details, set the platform and enter the id by hand. See Fix app details. “Could not read the package id from the file. Check the platform is correct, or enter the id manually.” means the same.
“Upload failed” / “Could not get the CDN URL for the uploaded file”App Library
Why
The file could not be stored: network or proxy problems, an expired session, or the library limit reached on the server. A server message may appear in Turkish (“App Library dolu…” means the library is full).
Fix
Sign in again, check that a proxy does not block large uploads, and try again. If the library is full, see above.
“Could not resolve the company context — refresh the page and try again”App Library
Fix
Reload the page. If it persists, sign out and in again.
“App details could not be updated” / “Invalid platform — only Android or iOS can be selected.” / “Failed to update the name” / “Delete failed”App Library
Why
The change was refused: you are not an admin, the platform value is not Android or iOS, or the app was removed meanwhile.
Fix
Reload the list and try again. Changing the library needs the Admin role.
“No apps yet. A company admin can add apps to the App Library.” / “No apps in library yet.”App Library
Fix
Ask an admin of your company to upload the build.

Access and farm runs#

I only see Test Agents, without the other tabsAccess
Why
The selected project is a WEB project. Web tests do not use devices, so the device tabs are hidden.
Fix
Select a MOBILE or DESKTOP project. See What you see.
“Run your mobile tests on real devices. This feature is not enabled on your account yet.”Access
Why
Your company does not have the Device Farm right.
Fix
Click Contact us to enable it and send the request. See Ask for the Device Farm right.
“Request could not be sent. Please try again.”Access
Fix
Try again in a minute, or write to info@smartestqa.ai.
The Nodes tab or device controls are missingAccess
Why
They depend on your role and installation: users of the cloud service have no Nodes tab, and only admins get node actions, device controls and App Library changes.
Fix
Ask an admin. See Who can do what.
“You are not authorized for this action.” / “You cannot view another company’s data.”Access
Why
The server refused the action for your role, or the request named another company.
Fix
Reload the page so it uses your own company, and ask an admin for actions your role does not have.
“The active company could not be determined. Refresh the page; if it persists, reselect your company from the top menu.” / “Your account’s company could not be resolved. Please sign out and sign in again.”Access
Fix
Reload the page. If the message stays, sign out and sign in again.
“Device Farm is not enabled for company. Enable it in that company’s licence to run tests on real devices.”Run
Why
A run targeted the Device Farm, but the project’s company has no Device Farm right.
Fix
Run on your own agent instead, or ask for the Device Farm right.
A farm run does not start: “concurrent session limit reached”, “platform not allowed”, “no available device for platform …”, “device busy”, “device is dedicated to another company”Run
Why
The run was refused before it started:
  • concurrent session limit reached (n): your company already runs n farm runs at once (cloud service only).
  • platform not allowed: your licence does not include this platform.
  • no available device / no allocatable device for platform: every matching device is busy, offline or marked Manual.
  • device busy: the device you picked is in use, also by a live session or the inspector.
  • A Turkish message mentioning EMULATOR_ONLY: your licence tier allows emulators only, not real devices.
Fix
Wait for running farm runs to finish, pick another device or platform, or let the run choose a device automatically. Check Devices for Available devices. For licence limits, contact info@smartestqa.ai.

Didn’t find your answer?Write to support with your project name and what you see on screen.

info@smartestqa.ai
© 2026 Selenity Technology · SmartestQAsmartestqa.aiThis page as MarkdownChecked against smarttest-fe predev 2a8c79cc (en.json, AgentPool, HostPerformancePanel, HostDevicesInline, LiveDeviceDialog, DeviceFarm components), smarttest-be 633c2a03 (HostServiceImpl, DeviceFarmAccessGuard, DeviceFarmEntitlementServiceImpl, DeviceFarmSessionController, DeviceFarmReaper)