Troubleshooting

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 127.0.0.1:8780.

• Start droidline serve and keep its window open. Closing the window stops the server.
• If you changed client.listen in config.toml, or set DROIDLINE_HOST or DROIDLINE_PORT, make sure your code uses the same address.
• 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.

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.

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:

   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.

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.

kill, clear_data or the network switches fail

These commands press buttons in Android's Settings app for you, which differs between brands and Android versions. MACRO_FAILED says which step could not be found.

• Make sure the screen is on and unlocked; call wake() first.
• Try again: the error is marked retryable, and a slow phone may simply have been late.
• If it fails every time on one phone model, please report it with the phone model, Android version and language. Reports like that are how these shortcuts learn new phones.

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.