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 serve and keep its window open. Closing the window stops the server.
  • If you changed client.listen in config.toml, the droidline commands follow it from version 0.1.9, but the SDKs don't read the config. Set DROIDLINE_PORT (and DROIDLINE_HOST if 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 doctor shows 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 serve may already be running, perhaps in another window or as a service. Stop it first.
  • To use other ports, change agent.listen, client.listen or discovery.listen in 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 doctor checks Droidline's three ports against these ranges and suggests a free port to put in config.toml. To see the ranges yourself, run netsh interface ipv4 show excludedportrange protocol=tcp (and protocol=udp for discovery).

The phone cannot find the PC

Pair on this Wi-Fi answers "No PC answered", or the phone never connects after pairing.

  1. Check that both are on the same Wi-Fi network. Guest networks and some mesh systems keep devices apart; use the main network.

  2. 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.

  3. Allow droidline through the firewall on private networks. If you dismissed the prompt, open Windows Security, Firewall & network protection, Allow an app through firewall, and tick Private for droidline. Or, in PowerShell as administrator:

    New-NetFirewallRule -DisplayName "Droidline" -Direction Inbound -Action Allow -Profile Private -Program "C:\Tools\droidline\droidline.exe"
  4. On macOS, open System Settings, Network, Firewall, Options, and allow incoming connections for droidline.

  5. 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.

  6. 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_FAILED on 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 pair again 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.

  1. In Droidline's Setup tab, set Battery optimization to Not restricted.

  2. Look for your brand's extra settings for background apps, and allow Droidline in each. They often look like this:

    BrandWhere to look
    SamsungSettings, Battery, Background usage limits: remove Droidline from Sleeping apps and Deep sleeping apps, or add it to Never sleeping apps
    Xiaomi, Redmi, POCOApp info, Autostart on, and Battery saver: No restrictions
    OPPO, OnePlus, realmeApp info, Battery usage, Allow background activity and Allow auto launch
    vivoSettings, Battery, Background power consumption management: allow Droidline
    Huawei, HonorSettings, 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.

  3. 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:

  1. Open Settings, Apps, Droidline (or tap App info on the Setup tab).
  2. Tap the three-dot menu in the top right corner and choose Allow restricted settings.
  3. 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 tap with 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 input with sendkey("enter").
  • input replaced text you wanted to keep: pass append=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_FOUND names the label it could not find. Open the same Settings page on your phone, look at the real labels with dump or droidline 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.
  • intent fails with BAD_ARGS: no screen on this phone handles that action, or it is not open to other apps.
  • clear_data answers NO_PERMISSION with the permission device_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.