In Appium, what does the appium:systemPort capability set on an Android session?

## What the capability actually names An Appium session that targets Android with the UiAutomator2 driver never touches the interface directly from the host machine. The driver installs and starts a small helper server on the device — `io.appium.uiautomator2.server`, with `io.appium.settings` beside it — and then drives the app by sending HTTP requests to that on-device server. Every element lookup, every tap and every page-source request in the session travels over that one channel. `appium:systemPort` is the host-side port number that channel uses. The test client talks to the Appium server over its own URL; inside that server, the UiAutomator2 driver reaches the on-device agent through the port this capability names. It is an ordinary per-session capability: it carries the `appium:` vendor prefix and travels in the `capabilities` body of `POST /session` exactly like `appium:automationName` or `appium:udid`. ## Why a second session cannot borrow it The capability has a single fixed default, and one session at a time never notices that. The moment a second Android session starts on the same host — a second worker in a parallel stage-crew call-sheet run, or a session left alive by a run somebody killed — both sessions want the same host port, and a host port has exactly one owner. Two outcomes are common: - The second session fails during startup, because the port it needs is already bound. - The second session starts cleanly, and its commands are answered by the agent already reachable on that port, so one phone performs both workers' taps while the other sits untouched. The second outcome is the expensive one, because nothing throws. The call-sheet suite reports assertion failures that look like flaky locators, a slow device or a bad build, and the actual cause is two workers sharing one channel into one device. ## What each simultaneous Android session needs Give every concurrent Android session its own value for each port it actually uses: - `appium:systemPort` — always, for any UiAutomator2 session. - `appium:chromedriverPort` — when the session drives Chrome or a web view, because that Chromedriver process binds a port of its own. - `appium:mjpegServerPort` — when the session streams screenshots, because the stream is forwarded to the host as well. - `appium:adbPort` — only when more than one adb server is in play on the machine. The usual pattern is arithmetic rather than a pool: each family gets a base number and each worker adds its index, so worker three's ports are deterministic, reproducible in a bug report, and cannot overlap worker four's. ## What it is not | Not this | What that actually is | |---|---| | The Appium server's own port | The server process listens on the port given by `--port`, and that is the URL a client is built on | | A device selector | `appium:udid` decides which device the session drives; the port decides how the driver reaches its agent | | An Apple-platform capability | Apple platforms do the same job under a different name, `appium:wdaLocalPort`, for WebDriverAgent | The last row is the one that surprises people who learned a single platform first. The Android per-session port set and the Apple per-session port set share almost no names, so a helper that assigns ports cannot be one list of capability names applied to both lanes — it has to branch on `platformName` before it picks anything. ## Reading a run that went wrong When a parallel Android lane degrades as workers are added, the port question is worth asking before the locator question: 1. Count the Appium sessions actually alive on the host, not the number the suite believes it started. 2. Confirm that each concurrent session received a distinct `appium:systemPort`, by logging the value next to the session id at session start. 3. Look for a stale forward held by a killed run, occupying a port a new session expects to own. 4. Only then go back to the locator, the wait or the device itself. ## What to remember `appium:systemPort` is not a tuning knob; it is an address. Setting it badly does not make a session slower — it collapses two sessions into one conversation with one device. The working rule is one distinct value per simultaneous Android session on the host, chosen deterministically rather than left at the default, and written into the run log so the choice can be checked afterwards rather than guessed at.