- Docs
- Resources
- Agent Pool & Device Farm
- Troubleshooting
Troubleshooting
Find the message or symptom you see. Each entry says why it happens, what to check and how to fix it.
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
- Search this page for the exact message you see (Ctrl+F).
- Open the entry and read Why first.
- Work through Check in order; most problems end there.
- 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
-
- Windows: you run it in PowerShell, not Command Prompt;
curl.exeexists (Windows 10 and 11 include it). - Linux:
curlandunzipare installed. - The machine can reach the download address and SmartestQA; a proxy may block one of them.
- You copied the command after selecting the right agent, so it carries that agent’s key.
- Windows: you run it in PowerShell, not Command Prompt;
- 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:4723and got no answer. Mobile tests and live sessions on your agent need it. - Check
- A terminal with
appiumis still open on the agent computer. - Nothing else uses port 4723.
- Hover the Appium chip for the address and error it reports.
- A terminal with
- 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
appiumin 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 -vand run the Appium command again.
adb devices lists the emulator as offline, or not at allSetup
- Check
- The emulator has finished starting and shows its home screen.
- Android SDK Platform-Tools is installed (step 2 of the guide).
- For a phone: USB debugging is on and you accepted the prompt on the phone.
- Fix
- Wait for the emulator, then run
adb devicesagain. 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 -pshould print/Applications/Xcode.app/Contents/Developer;appium driver doctor mac2lists 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, runappium 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-authenticationonce, 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
- The device is Available (farm) or listed under Connected Devices (agent).
- The node or agent is Online.
- 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
- The node computer is on and the client runs with the node’s key.
- Last Heartbeat in Nodes.
- 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
.ipafor a simulator), upload the right file.
“No runs yet” / “No runs match these filters.”Runs
“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.zipof an iOS simulator.appfolder. 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