skip to content

In Appium on Android, how do appium:systemPort and UiAutomator2's serverPort setting differ?

level: middleimportance: should knowfreq 38%

answer

  1. two ends of one connection
  2. one is a capability, one a setting
  3. host side versus device side
  4. the README says do not mix them
  5. unique per concurrent Android session

basics

~20 s

They sit on opposite ends of the same connection. appium:systemPort is the port the driver reaches the UiAutomator2 server on from the host, while UiAutomator2's serverPort setting is the port the server binds on the Android device itself.

solid answer

~40 s

Both name a port in Appium's UiAutomator2 architecture on Android, but on different sides of the wire. `appium:systemPort` is a **capability**: the port the host-side driver uses to reach the on-device UiAutomator2 server, and the one that must be unique per concurrent Android session. The UiAutomator2 **setting** `serverPort` is described by the driver's own README as "the port on the remote device to start UiAutomator2 server on", followed by the blunt warning "Do not mix this with `systemPort`". A third name is easy to fold into both and should not be: `appium:mjpegServerPort` addresses the screenshot stream, is declared by the UiAutomator2 and XCUITest drivers alike, and means a host-forwarded port on Android but WebDriverAgent's own broadcast port on Apple platforms.

code

json · 12 lines
json
{
  "capabilities": {
    "alwaysMatch": {
      "platformName": "Android",
      "appium:automationName": "UiAutomator2",
      "appium:appPackage": "com.example.foodtruck.preorder",
      "appium:systemPort": 8201,
      "appium:settings[serverPort]": 6791
    },
    "firstMatch": [{}]
  }
}

go deeper

for a junior

Be ready to say that appium:systemPort is how the host-side Appium driver reaches the UiAutomator2 server on an Android device, and that a different knob controls the port on the device end.

for a middle

Explain both ends of the connection and the capability-versus-setting distinction, and quote the UiAutomator2 documentation's own warning not to mix serverPort with systemPort.

for a senior

Diagnose from symptoms. Say which knob you would move when concurrent Android sessions cross-talk on one host, and why moving the device-side port would not help.

for a principal

Own the naming discipline across a cross-platform suite: the Apple side uses different capability names entirely, and appium:mjpegServerPort is one shared name over two mechanisms, so configuration abstractions must not pretend the platforms are symmetric.

## Two ports, two sides of the same wire Appium's UiAutomator2 driver on Android is a client-and-agent design: a host-side driver talking over HTTP to a server running on the device. Any connection like that has two endpoints, and Appium exposes a knob for each. Confusing them is common precisely because both names contain the word "port" and both appear in the same parallel-run advice. - **`appium:systemPort`** is a capability, sent when the session is created. It is the port the driver reaches the UiAutomator2 server on from the machine running the Appium server. - **`serverPort`** is a UiAutomator2 **setting**, not a capability namespace of its own. The driver's README defines it as "the port on the remote device to start UiAutomator2 server on" and adds, verbatim, "Do not mix this with `systemPort`." The README does not usually issue warnings like that; this one exists because the mistake is so easy to make. ## Why two knobs exist at all The host and the device are different address spaces. The number the driver dials is not necessarily the number the server binds. Splitting them lets you resolve two independent kinds of collision: 1. A collision on the **host**, where several Appium sessions on one machine would otherwise contend for the same local port. That is `appium:systemPort`'s job, and it is the capability parallel-run guidance singles out. 2. A collision on the **device**, where the port the server wants to listen on is taken or blocked. That is what the `serverPort` setting exists for. Most suites only ever touch the first. The second is a specialist knob you reach for when the device side genuinely conflicts. ## A third port that is not either of them | Name | Kind | What it addresses | |---|---|---| | `appium:systemPort` | capability | The port the driver reaches the Android UiAutomator2 server on | | `serverPort` | UiAutomator2 setting | The port the server binds on the Android device | | `appium:mjpegServerPort` | capability | The MJPEG screenshot stream, on both Android and Apple platforms | | `appium:adbPort`, `appium:remoteAdbHost` | capabilities | Reaching the Android debug bridge itself | `appium:mjpegServerPort` deserves special care because it is **the same capability name on both platforms and two different mechanisms underneath**: on Android it is a host-forwarded port, and on Apple platforms it is WebDriverAgent's own broadcast port. `appium:mjpegScreenshotUrl` is shared the same way. The Apple equivalents of `appium:systemPort` — `appium:wdaLocalPort`, `appium:wdaRemotePort`, `appium:wdaBindingIP`, `appium:webDriverAgentUrl` — share no name with the Android ones at all, so nothing about them transfers by guesswork. ## What it looks like when you get it wrong Picture a food-truck pre-order suite running three Android sessions at once on a single host to cover the lunch-rush order flow on three devices. - If all three sessions send the same `appium:systemPort`, the driver instances contend for one host port. Sessions start and then behave as though commands are landing on the wrong device — the food truck's menu opens on a device the test did not address. - If someone "fixes" that by pinning the `serverPort` setting instead, the host-side collision is untouched, because that setting changes the device end of the connection. - If someone assumes `appium:mjpegServerPort` and `appium:systemPort` are alternative spellings of one idea, they will pin one and leave the other shared, which fixes screenshots and nothing else. The diagnostic habit that avoids all three: before changing a port, say out loud which end of the connection it lives on. ## A short checklist - Ask whether the knob is a **capability** sent at session creation or a **setting** applied to the running UiAutomator2 session. `appium:systemPort` is the first; `serverPort` is the second. - Ask which **side** it addresses: host or Android device. - Ask whether the name is **platform-specific or shared**. `appium:mjpegServerPort` is shared in name and split in mechanism; the WebDriverAgent port capabilities on Apple platforms are not shared at all. - Change one knob at a time, and re-read the symptom before changing another. ## The answer in one breath `appium:systemPort` is the capability naming the port the driver reaches the Android UiAutomator2 server on; `serverPort` is the UiAutomator2 setting naming the port that server binds on the device; the driver's own documentation warns you not to mix them; and `appium:mjpegServerPort` is a separate concern that happens to look like both. Say that, name Android explicitly, and note that the Apple side uses entirely different capability names — an interviewer will hear an engineer who has actually configured a parallel Android run rather than copied a snippet.

  • Which of the two would you change first when two concurrent Android sessions interfere on one host?
    `appium:systemPort`, because the contention is on the host side: each concurrent session needs its own value. The UiAutomator2 `serverPort` setting addresses the device end of the connection and leaves a host-side collision exactly as it was.
  • Does appium:mjpegServerPort mean the same thing on Android and on Apple platforms?
    The name is shared but the mechanism is not. On Android it is a host-forwarded port for the screenshot stream; on Apple platforms it is WebDriverAgent's own broadcast port. Both parallel-run guides list it as must-be-unique per worker, so the operational advice matches even though the underlying mechanism differs.

saying these in an interview costs you the question

  • Using appium:systemPort and the serverPort setting interchangeably for one port
  • Assuming appium:systemPort is the port the Appium server serves clients on
  • Thinking appium:wdaLocalPort applies to an Android UiAutomator2 session
  • Believing appium:mjpegServerPort means the same mechanism on Android and Apple platforms
  • Treating serverPort as a capability rather than a UiAutomator2 setting
  • Changing several port knobs at once and calling the result a fix