Troubleshooting
Fixes for the problems people meet most, by symptom: the server, pairing, phones going offline, permissions, elements that are not found, typing, screenshots and Settings recipes.
Start every investigation with these two commands. doctor checks the setup; serve --verbose shows every connection attempt as it happens:
droidline doctor
droidline serve --verbose
Find your symptom below. Problems that only happen away from your Wi-Fi are in Troubleshooting connections.
My code says the server is not running
SERVER_NOT_RUNNING (Python ServerNotRunningError) means nothing answered on the client address, which is 127.0.0.1:8780 unless you changed it.
- Start
droidline serveand keep its window open. Closing the window stops the server. - If you changed
client.listeninconfig.toml, thedroidlinecommands follow it from version 0.1.9, but the SDKs don't read the config. SetDROIDLINE_PORT(andDROIDLINE_HOSTif needed) to the same address for your scripts. - The CLI's error names the address it tried, for example
(nothing answered at 127.0.0.1:8780). droidline doctorshows the address it tried and whether the agent port is free.
The server does not start
An error such as "address already in use" means another program holds one of Droidline's ports: 8779 for phones, 8780 for your code, 8778 for discovery on Wi-Fi.
- Another
droidline servemay already be running, perhaps in another window or as a service. Stop it first. - To use other ports, change
agent.listen,client.listenordiscovery.listenin config.toml. Phones learn the new agent port the next time they pair. - On Windows, a port can be unusable even though no program holds it, because Windows keeps whole ranges for itself, often for Hyper-V, WSL or Docker. From version 0.1.10,
droidline doctorchecks Droidline's three ports against these ranges and suggests a free port to put inconfig.toml. To see the ranges yourself, runnetsh interface ipv4 show excludedportrange protocol=tcp(andprotocol=udpfor discovery).
The phone cannot find the PC
Pair on this Wi-Fi answers "No PC answered", or the phone never connects after pairing.
-
Check that both are on the same Wi-Fi network. Guest networks and some mesh systems keep devices apart; use the main network.
-
On Windows, set the network to private: Settings, Network & internet, Wi-Fi, your network, Network profile type: Private. Windows blocks incoming connections on public networks.
-
Allow
droidlinethrough the firewall on private networks. If you dismissed the prompt, open Windows Security, Firewall & network protection, Allow an app through firewall, and tick Private fordroidline. Or, in PowerShell as administrator:New-NetFirewallRule -DisplayName "Droidline" -Direction Inbound -Action Allow -Profile Private -Program "C:\Tools\droidline\droidline.exe" -
On macOS, open System Settings, Network, Firewall, Options, and allow incoming connections for
droidline. -
A VPN running on the PC can hide it from the local network. Pause it while pairing, or pair with the QR code, which carries the PC's address.
-
The 6-digit route finds the PC with a UDP broadcast on port 8778. Some routers and firewalls let the phone's TCP connection through but drop these broadcasts, so the phone could connect yet never hears the PC. The QR code skips this step.
If the 6-digit route still fails, the QR code usually works: run droidline pair and scan it.
Pairing fails
PAIRING_FAILEDon the PC means no phone is waiting with that code. Codes expire after 5 minutes; tap Pair on this Wi-Fi again for a new one.- A QR code is valid for 10 minutes and pairs one phone. Run
droidline pairagain for the next phone. - The app says the PC does not recognize it: the phone was removed with
droidline revoke, or the server's settings folder was deleted or moved. Pair again.
The phone goes offline when the screen turns off
Android and many phone brands stop background apps to save battery. Droidline needs to keep its connection open.
-
In Droidline's Setup tab, set Battery optimization to Not restricted.
-
Look for your brand's extra settings for background apps, and allow Droidline in each. They often look like this:
Brand Where to look Samsung Settings, Battery, Background usage limits: remove Droidline from Sleeping apps and Deep sleeping apps, or add it to Never sleeping apps Xiaomi, Redmi, POCO App info, Autostart on, and Battery saver: No restrictions OPPO, OnePlus, realme App info, Battery usage, Allow background activity and Allow auto launch vivo Settings, Battery, Background power consumption management: allow Droidline Huawei, Honor Settings, Battery, App launch: set Droidline to Manage manually with every switch on Menu names change between versions; search the settings for "battery" or "background" if they differ.
-
Keep the phone charging if it runs unattended.
The app's Status tab shows the connection state and the route in use, which helps tell a sleeping app from a network problem.
The accessibility switch is greyed out
On Android 13 and later, apps installed from a file are blocked from accessibility until you allow restricted settings:
- Open Settings, Apps, Droidline (or tap App info on the Setup tab).
- Tap the three-dot menu in the top right corner and choose Allow restricted settings.
- Go back to accessibility settings and turn Droidline on.
If the menu item is missing, open the accessibility setting once first so Android registers the attempt, then look again.
Accessibility keeps turning itself off
Commands then fail with NO_ACCESSIBILITY. Some phones turn accessibility services off after the app updates, after a crash, or when a battery saver kills the app.
- Turn it on again from the Setup tab.
- Apply the battery steps above; they prevent most cases.
- After installing an update of the Droidline app, check the Setup tab once.
A command cannot find an element I can see
NOT_FOUND although the element is on the screen. Go through the checklist in Finding elements. The usual causes:
- The text differs slightly: capital letters, a trailing space, a different language. Copy the value from
droidline dump. - The element is in a system window such as a permission dialog. Dump with
all_windows=True. - The screen has no elements at all (games, maps, canvas pages). Use
tapwith coordinates.
Typing does not work
NO_IME: the Droidline keyboard is not enabled or not selected. Turn it on and select it from the Setup tab.- The text appears but the app does not react, for example a search box that waits for Enter: follow
inputwithsendkey("enter"). inputreplaced text you wanted to keep: passappend=True.
Screenshots fail on Android 9 or 10
Before Android 11, screenshots need Android's screen capture permission. The first screenshot shows a prompt on the phone; tap Start now. Until someone accepts it, screenshot fails with NO_PERMISSION and capture appears under MISSING in droidline devices.
A Settings recipe does not work on my phone
The Settings recipes for force stop, clearing data and the network switches press buttons in Android's Settings app, which differs by phone maker, Android version and language. They were checked on Samsung phones in Korean.
- Make sure the screen is on and unlocked; call
wake()first. - A
NOT_FOUNDnames the label it could not find. Open the same Settings page on your phone, look at the real labels withdumpordroidline inspect, and adjust the pattern in the recipe. - A confirmation dialog stays open: the recipes press
android:id/button1, the standard confirm button of Android dialogs. If your phone's dialog uses another button, select it by its text instead. intentfails withBAD_ARGS: no screen on this phone handles that action, or it is not open to other apps.clear_dataanswersNO_PERMISSIONwith the permissiondevice_owner: it only works in device owner mode. Without it, use the recipe that goes through Settings.
Several phones are online and commands fail
DEVICE_AMBIGUOUS means more than one phone is online and the command did not say which. Name the phone: connect("shelf-01"), --device shelf-01, /devices/shelf-01/..., or set DROIDLINE_DEVICE.
A command failed with AGENT_RESTARTED
The Droidline app on the phone restarted while the command was in flight, so Droidline cannot tell whether it ran. Check the screen, then decide whether running it again is safe. Frequent restarts usually point to the battery settings above.
Still stuck
Open an issue on GitHub with the output of droidline doctor, the phone's model and Android version, and the smallest script that shows the problem. Leave out tokens, passwords and personal data.