Troubleshooting Device Connect
To find and fix most problems with Device Connect for AWS Device Farm, run the devicefarm-connect doctor
command first. If the doctor finds no problem, search this page for the message that you see. In the
examples, replace each session ARN with your session ARN.
Topics
Run the doctor command
The devicefarm-connect doctor command checks your computer, your AWS credentials,
and your remote access session. It reports one row for each category. It doesn't start a bridge or
change a running one. For each problem that
it finds, it gives you the command to run.
To run the doctor command
-
Open the shell that you use to run
devicefarm-connect bridge start. The bridge uses the AWS credentials and environment of that shell. -
Run the doctor with the Amazon Resource Name (ARN) of your remote access session:
devicefarm-connect doctor --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" -
If a row is
WARNorFAIL, run the command that each item in theWhat to dolist gives. -
Run the doctor again until no row is
FAIL.
For example, the following command runs the doctor while a local Android Debug Bridge (adb) server holds port 5037.
devicefarm-connect doctor
This will show output such as the following:
+---------------+--------+-----------------------------------------------------+
| Category | Status | Details |
+---------------+--------+-----------------------------------------------------+
| Local machine | WARN | listen port: an adb server (version 41) is |
| | | listening on 127.0.0.1:5037 |
| | | also passed: working directory, bridge, adb forward |
+---------------+--------+-----------------------------------------------------+
| AWS | PASS | AWS credentials |
| | | remote access session not checked: pass |
| | | --session-arn to check the session, the device |
| | | connection, and adb versions |
+---------------+--------+-----------------------------------------------------+
| Network | SKIP | not checked: needs remote access session |
+---------------+--------+-----------------------------------------------------+
| Dependencies | SKIP | not checked: needs remote access session |
+---------------+--------+-----------------------------------------------------+
What to do
1. Local machine, listen port: an adb server is listening on 127.0.0.1:5037, so
the bridge cannot bind it until that server stops. Run
'devicefarm-connect bridge start --port 5037': it stops that server first
(via 'adb kill-server'). If a program that restarts adb automatically, such
as Android Studio, takes the port back, quit that program, run
'devicefarm-connect bridge start --port 5037' again, then open it: it then
uses the bridge as its adb server on port 5037.
doctor: 1 of 4 categories passed, 1 warning, 2 not checked
A running bridge with adb reverse turned off makes the Local machine row WARN. You
can ignore this warning if you don't use adb reverse. The doctor's bridge check also
gives WARN and the reason when the bridge detached a device itself, or when the
--session-arn session is not attached.
If you started the bridge on a port other than 5037, add the same --port option to
the doctor, for example --port 5038.
For the list of checks, the output formats, and the exit codes, see devicefarm-connect doctor.
Reading error messages
When a devicefarm-connect command fails, it prints an error to stderr and exits
with code 1. The error has the following shape:
devicefarm-connect: error: problem
cause: cause
fix: fix
The error: line says what failed. Each cause: line says why, and each
fix: line says what to do. An error can have several cause and fix lines. Some errors have
only the error line.
For example, a mistake on the command line ends with a fix line that points to the help.
devicefarm-connect bridge bogus
This will show output such as the following:
devicefarm-connect: error: unknown command "bogus" for "devicefarm-connect bridge"
fix: run 'devicefarm-connect bridge --help' for usage
Lines that start with * are progress notes, not errors. Lines with time= and
level= appear only with --debug.
Messages that start with error: or adb: come from adb. For more detail, read the
log file of the bridge. For its location, see Finding the log file.
Problems when the bridge starts
The bridge starts when you run devicefarm-connect bridge start. It also starts
when devicefarm-connect device add or devicefarm-connect device list
finds no running bridge. The following table lists messages that you can see at that time. The
sections after the table cover the local adb server and the port.
| Message or symptom | Cause | What to do |
|---|---|---|
The shell can't find |
The install folder is not on your |
Add the install folder to your |
|
The bridge failed while it started. For example, a malformed AWS config
profile or |
Fix what the message names. Then run |
|
The bridge didn't finish starting. |
Read the log file that the message names. Then run |
|
Another program held the port for a short time while the bridge started. |
Run |
|
The |
Run |
|
|
Run |
|
Another user owns the working directory. This happens on macOS and Linux when
|
Set |
|
On Windows, the working directory is in |
Set |
|
A registered bridge no longer answers. For example, it hangs. |
Run |
The doctor says |
You updated |
Run the commands that the doctor gives: |
Local devices disappear, or Android Studio takes port 5037 back
For example, you run the following command while a local adb server holds port 5037.
devicefarm-connect bridge start
This will show output such as the following:
* bridge not running; starting it now
* stopped the adb server on 127.0.0.1:5037 (via 'adb kill-server')
* bridge started (PID 4242); log file: /run/user/1000/devicefarm-connect/devicefarm-connect.log
devicefarm-connect listening on port 5037 with no device attached; use 'device add' to connect one
This is expected. The bridge takes the place of your local adb server on port 5037, so it
stops that server first, as adb kill-server does. The local devices that the
server served then disappear from adb. Through the bridge, adb shows only
Device Farm devices. device add and device list start the bridge
the same way, so they also stop the server.
To use your local devices again
-
Stop the bridge:
devicefarm-connect bridge stop -
Run any adb command, such as
adb devices. adb starts its own server again, and that server serves your local devices.
To keep your local adb server and the bridge at the same time, start the bridge on another port. For more information, see Using a different port.
A program that restarts adb automatically, such as Android Studio, can keep port 5037 or take it
back. Then
devicefarm-connect prints a message such as the following. A similar message starts
with an adb server took 127.0.0.1:5037 before the bridge could bind it.
devicefarm-connect: error: could not start the bridge
cause: an adb server on 127.0.0.1:5037 was asked to stop (via 'adb kill-server') and did not (it answered OKAY but port 5037 is still held after 1s; a program that restarts adb automatically, such as Android Studio, can take it back at once). Quit the program that started adb, such as Android Studio, run 'devicefarm-connect bridge start --port 5037', then open that program again: it then uses the bridge as its adb server on port 5037.
To use the bridge with a program that restarts adb
-
Quit the program, such as Android Studio.
-
Start the bridge:
devicefarm-connect bridge start -
Open the program again. It now uses the bridge as its adb server on port 5037.
For more information about Android Studio, see Using Android Studio.
The bridge can't use the port
devicefarm-connect prints one of the following messages when the bridge
can't listen on the port.
| Message | Cause | What to do |
|---|---|---|
|
A program that is not adb holds the port. |
Stop that program, then run |
|
A bridge started from another working directory or by another user holds the port. |
Run |
|
On macOS and Linux, a port lower than 1024 needs administrator rights. On
Windows, the message has a Windows error text instead of |
Use another port. On Windows, choose a port outside the reserved ranges. |
|
The |
Pass a port from 1 to 65535. |
On Windows, to list the reserved port ranges, run the following command:
netsh int ipv4 show excludedportrange protocol=tcp
To start the bridge on another port
-
Check the port that you want to use. The
Local machinerow passes when the port is free.devicefarm-connect doctor --port 5038 -
Start the bridge on that port:
devicefarm-connect bridge start --port 5038 -
Add
-Pwith that port to every adb command, for example:adb -P 5038 devices
For more information, see Using a different port.
Credential and attach problems
When an attach fails, devicefarm-connect device add prints could not attach
the device. The cause: line names what
failed, and the fix: line names the command to run.
The bridge keeps running. A fix that restarts the bridge names two commands:
devicefarm-connect bridge start, which stops the running bridge first and starts one that
reads the AWS settings of your shell, then devicefarm-connect device add, which attaches
the device again. The sections after the table cover credentials and the session status.
| Message | Cause | What to do |
|---|---|---|
|
The value is not a remote access session ARN. For example, it is a device ARN or a
project ARN. A session ARN contains |
Pass the session ARN that |
|
The session is in another Region. The |
Create the session in the US West (Oregon) Region. Pass |
|
The session's device is an iOS device or runs Android 8 or earlier. |
Stop the session, because Device Farm bills it until you stop it. Then create a session on a device that runs Android 9 or later. |
|
The ARN is wrong, or the session belongs to another AWS account. |
Check that you copied the whole ARN. In the shell that started the bridge,
run |
|
Device Farm throttled the lookup, or the network was slow. |
Wait a moment, then run |
|
The remote adb server lists no device, so the bridge can't read the serial of the device. The problem is on the Device Farm side. |
Wait a moment, then run |
|
The session is ending, for example because nothing was connected to it for a few minutes. |
Start a new session and attach it. |
|
The session ended, the endpoint URL expired, or the ARN names another account. |
Run |
|
At this time, Device Connect works only with metered public devices. The reason says
what the session doesn't meet: |
Stop the session. Create a remote access session on a public device with the
|
|
The device didn't answer in time, or the connection dropped while the bridge waited for it. |
Run |
|
This is a note, not an error. The ARN you typed carries another account ID. The bridge attached the session under the ARN the service returned. |
Use the printed ARN with |
|
The device of another session is attached. The bridge holds one device at a time. |
Run |
Renew the credentials of the bridge
The bridge reads AWS credentials from the shell that started it. If you change the
credentials or AWS_PROFILE in a shell later, the bridge doesn't see the change. The
following messages mean that the bridge needs new or fixed credentials.
| Message | Cause | What to fix first |
|---|---|---|
|
The credentials don't allow |
Allow |
|
The credentials are expired or wrong, the request signature is bad, or the clock of your computer is wrong. |
Run |
The doctor says |
The bridge started from a shell with no credentials. For example, you
ran |
Set |
|
The credentials of the bridge expired, so it detached the device. |
Refresh the credentials. Then, from that shell, restart the bridge with
|
|
The credentials of the bridge lost their permission. |
Fix the credentials or their permission. Then, from that shell, restart the
bridge with |
After you fix the credentials, give them to the bridge. If the bridge uses an IAM Identity Center (SSO) profile, you don't need to restart it.
To renew the credentials of an SSO profile
-
Refresh the token. The bridge reads the new token.
aws sso login --profileprofile-name -
If the bridge detached a device, attach it again:
devicefarm-connect device add --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000"
For other credentials, restart the bridge from a shell with working credentials.
To restart the bridge with new credentials
-
Open a shell and fix the credentials. For example, set
AWS_PROFILEor export new keys. In PowerShell, set a variable in the form$env:AWS_PROFILE = '.profile-name' -
Run the doctor, and check that the AWS row is not
FAIL:devicefarm-connect doctor --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" -
From the same shell, restart the bridge.
bridge startstops a running bridge first. If you started the bridge with other options, such as--port, add them.devicefarm-connect bridge start -
Attach the device.
devicefarm-connect device add --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" -
Add your forward and reverse rules again.
The session is not RUNNING, or has ended
When you attach the device, the cause line reads like one of the following:
remote access session "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" is not running yet (status PREPARING)
remote access session "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" has ended (status COMPLETED)
When the session ends while the device is attached, adb prints a message such as the following. The
message can also say is stopping or no longer exists.
error: remote access session arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000 has ended (COMPLETED); start a new remote access session, then run 'devicefarm-connect device add --session-arn <new ARN>'
Later adb commands print the same reason, until you attach a device again.
You can attach a session only while its status is RUNNING. A session ends when you stop
it, when it reaches its maximum length, or when it fails before RUNNING. For the session
length, see Service limits. The bridge then
detaches the device and keeps running. Until it detaches the device, adb devices
can still list it.
The following table shows what to do for each session status.
| Status | Meaning | What to do |
|---|---|---|
|
The session is still starting. |
Keep checking the status. |
|
Your account is at its remote access concurrency limit. |
Wait, or stop another session. |
|
The device is busy or not ready yet. |
Wait. After more than 2 minutes, stop the session. Then create a new session, on another device if you can. |
|
The session is ready. |
Attach the device with |
|
The session is ending. This is not the end state. |
Wait for |
|
The session ended. |
Create a new session. |
To attach a session after it starts
-
Check the session status every 20 seconds until it is
RUNNING:aws devicefarm get-remote-access-session --arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" --query remoteAccessSession.status --output text --region us-west-2This will show output such as the following:
RUNNING -
Attach the device:
devicefarm-connect device add --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000"
If the session ended, create a new session, and attach the device with the new session ARN. For instructions, see Step 2: Create a remote access session.
Problems with adb commands
adb prints the following messages when you run adb commands through the bridge. The sections after the table cover the adb version and a device that detached.
| Message or symptom | Cause | What to do |
|---|---|---|
|
Device Farm refused a new adb connection to the device. The text after the colon is
the reason from Device Farm. |
Run the command again. If the error remains, run |
|
Device Farm closed a new adb connection before the device answered.
|
Run the command again. If the error remains, run |
|
Device Farm refuses some adb commands. A refusal ends only that adb connection. The device stays attached and usable. |
Remove the command from your workflow. For more information, see Supported adb commands. To stop the bridge, run
|
|
The bridge has the maximum number of open adb connections to the device. The limit counts local, forwarded, and reverse connections together. |
Close the shells, logcat streams, and forwarded connections that you don't need. |
|
The serial or transport ID does not match the attached device. |
Run |
|
The cause line names the problem: |
To detach the attached device, run |
adb server version doesn't match this client
adb prints messages such as the following:
adb server version (41) doesn't match this client (40); killing...
ADB server didn't ACK
could not install *smartsocket* listener: Address already in use
error: cannot connect to daemon
Your adb must be version 1.0.41. An adb with another version can't connect through the bridge,
so every command fails. The doctor's Dependencies row then says that your adb
differs from the remote adb server.
To use adb version 1.0.41
-
Check your adb version:
adb version -
If the first line is not
Android Debug Bridge version 1.0.41, install Android SDK Platform-Tools whose adb is 1.0.41, such as Platform-Tools 37. In Android Studio, update Android SDK Platform-Tools in the SDK Manager. -
Put the directory of that adb first on your
PATH. -
Run the doctor. It checks every adb that it finds on your computer.
devicefarm-connect doctor --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000"
A device detached, or adb lists no device
A device that you attached is gone, or its adb commands fail. For example, adb prints adb: no
devices/emulators found, followed by the reason when the bridge detached the device
itself, or an adb shell stops after your network drops. adb wait-for-device waits
until you attach a device.
The bridge looks up the session every few minutes. When a lookup fails after retries, the bridge detaches the device and closes its forward rules and connections. A lookup fails when the session ended, when the credentials expired or lost their permission, or when a network outage lasted through the lookup.
A short network drop doesn't stop an open adb connection, but a drop of about 20 seconds closes it.
adb devices can still list a device for a few minutes after its commands start to
fail.
To attach the device again
-
Check the bridge. If it detached a device on its own, the output gives the reason.
devicefarm-connect bridge statusThis will show output such as the following:
devicefarm-connect bridge is running (PID 4242), no device attached; the last device detached 42 seconds ago: the bridge could not look up remote access session arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000:error; run 'devicefarm-connect device add --session-arn arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000' to attach it again -
Fix the cause. For a network problem, see Network problems. For a credential problem, see Renew the credentials of the bridge. For a session that ended, see The session is not RUNNING, or has ended.
-
Attach the device again:
devicefarm-connect device add --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" -
Add the forward rules of the device again.
Problems with adb forward and adb reverse
The following table lists messages for port forwarding rules. For the rules that Device Connect supports, see Supported port forwarding. The section after the table covers adb reverse when it is turned off.
| Message or symptom | Cause | What to do |
|---|---|---|
|
The bridge was still preparing |
Run the |
|
Another computer attached the same device with adb reverse on. Only one computer
at a time can use |
On the other computer, run |
|
Device Farm refuses |
Choose a device port outside 5555 to 5585, for example |
|
The reverse rule names the adb port of the bridge as the port on your computer. The bridge refuses the rule. |
Name the port of the server on your computer that the device must reach. |
Reverse traffic never reaches your computer. The log shows |
No server on your computer listens on the port of the rule, or the bridge refused the port. |
Read the reason in the log. Run |
|
For |
For |
|
The end of an |
Use |
|
The device end of the rule is not a |
Use |
|
An |
Use |
|
The device has the maximum number of rules. |
Run |
A forwarded connection opens, then closes with no data |
Nothing listens on the device port, or the device port is from 5555 to 5585. |
Make sure that the app on the device listens on the port in the rule. If the port is from 5555 to 5585, remove the rule and add it again with a device port outside that range. |
adb reverse is off for this bridge
adb prints a message such as the following:
error: adb reverse is off for this bridge. '--allow-adb-reverse' turns it on and lets the device open connections to this machine, so use it only with a device you trust. Run 'devicefarm-connect doctor --port 5037' for the commands that restart the bridge with reverse on and attach the device again.
adb reverse is off by default. With it off, no connection from the device reaches your computer.
--allow-adb-reverse lets the device open connections to this machine, so use it
only with a device you trust; a public device can run software you do not control.
To turn on adb reverse, see Reaching your computer from the device with adb reverse.
Problems on Windows
The following problems happen on Windows only. For the working directory and port messages on Windows, see Problems when the bridge starts and The bridge can't use the port.
| Message or symptom | Cause | What to do |
|---|---|---|
A window opens, says that the program is a command line tool, and closes after a few seconds. |
You started |
Open PowerShell or |
Windows shows a SmartScreen notice. |
Windows can show the notice for a new release, until Windows has seen the
file often. The Windows file has an Authenticode signature from |
Verify the download first. For instructions, see Verify your download. Then choose More
info. If Windows names a publisher, the publisher must be |
|
You started the bridge from an elevated shell. |
Open PowerShell as an administrator, and run |
Network problems
Device Connect needs the following outbound connections from your computer. It needs no inbound ports.
-
HTTPS on port 443 to
devicefarm.us-west-2.amazonaws.com, for the Device Farm API. This connection usesHTTPS_PROXY. Your credentials might also need to reach AWS STS, IAM Identity Center, or instance metadata endpoints. -
A TLS WebSocket (
wss://) to the session's device endpoint,devicefarm-interactive-global.us-west-2.api.awson TCP port 443, for adb traffic. This connection doesn't useHTTPS_PROXY. It needs a direct outbound connection.
On your computer, the bridge and each forward rule listen on 127.0.0.1. Reverse
connections connect to 127.0.0.1. Sandboxes, containers, and local firewalls must allow this.
The following table lists network messages.
| Message or symptom | Cause | What to do |
|---|---|---|
|
A proxy or security device on your network inspects TLS traffic, and your operating system doesn't trust its certificate. Device Connect uses the trust store of your operating system and TLS 1.2 or later. It has no option to skip certificate checks. |
Allow direct TLS connections from your computer to Device Farm, or add the
certificate of that proxy or security device to your trust store. Then run |
Device Farm API calls work through a proxy, but adb commands to the device fail |
The adb connections to the device don't use |
Run the doctor. When |
|
Your computer can't open the WebSocket connection to the device endpoint. For example, a firewall or a proxy on your network blocks it. For an adb command, the connection failed two times in a row. |
Check that your computer can reach the host that the message names on TCP port
443. If a firewall or a proxy blocks the connection, ask your network administrator to allow
direct outbound WebSocket connections ( |
The doctor says |
Your computer can't reach the Device Farm API, or Device Farm returned an error. |
Check that your computer can reach |
The doctor says |
A sandbox, a container, or a local firewall stops
|
Allow |
The doctor says |
The adb server next to the device didn't answer the doctor's version request. |
Wait, then run the doctor again. If the problem continues, contact AWS Support. |
|
The session returned a device endpoint that is not |
Run the doctor command on the |