skip to content

What do Appium's `--port` and `--base-path` server flags change about the running server?

level: juniorimportance: should knowfreq 58%

answer

  1. two flags, one number one prefix
  2. 4723 unless told otherwise
  3. prefix sits in front of /session
  4. -p and -pa are the short forms

basics

~20 s

The port flag sets the TCP port the Appium server listens on, 4723 by default. The base path flag sets the prefix every WebDriver route is mounted under, so a new session is posted to that prefix plus slash session.

solid answer

~40 s

`--port` (short `-p`) is the TCP port the server listens on; left alone it is `4723`. `--base-path` (short `-pa`) is the path prefix the whole route table is mounted under: with `--base-path /wd/hub`, a new session is `POST /wd/hub/session` instead of `POST /session`, and every later request for that session carries the prefix too. With no `--base-path` the routes sit at the root, which is why a suite carried over from an older setup that still appends `/wd/hub` fails on its very first request. `--address` (`-a`) is the third of the trio and picks the interface to bind. None of the three is platform-specific — the same port and prefix serve a session the Android UiAutomator2 driver answers and one the Apple XCUITest driver answers.

code

bash · 1 line
bash
appium --address 127.0.0.1 --port 4726 --base-path /wd/hub

go deeper

for a junior

Know both flags by name and effect: one is the port the Appium server listens on, the other is the prefix in front of every route. Be able to say where a new session is posted once a base path is set.

for a middle

Explain that the prefix is mounted in front of the whole route table rather than one route, and why two servers on one box need different ports even when their base paths differ.

for a senior

Be ready to say why you pin address, port and prefix explicitly on an unattended box, and how you diagnose a suite that never creates a session and leaves no device-side evidence.

for a principal

Own the fleet convention: one base path everywhere, ports allocated by rule rather than habit, and every box's URL written where a suite author finds it without asking.

## Two flags, two layers of the same address `--port` and `--base-path` both change where a client must aim at an Appium server, but they act on different layers. - `--port` (short form `-p`) is a **transport** setting: the TCP port the server process listens on. Left alone it is `4723`. - `--base-path` (short form `-pa`) is a **routing** setting: the path prefix the server mounts its whole WebDriver route table under. It does not open a second listener; it moves the routes inside the one `--port` already created. A third flag belongs in the same breath. `--address` (`-a`) picks which network interface the server binds — loopback only, or an interface other machines can reach. Interface, port and prefix together are the whole answer to "where is this server", and on an unattended box all three are worth writing down rather than inheriting. ## What the base path actually rewrites Every route hangs off the prefix, not only the first one. Started with `--base-path /wd/hub`, the server answers: - `POST /wd/hub/session` to create a session, - `GET /wd/hub/session/:sessionId/source` for that session's page source, - `DELETE /wd/hub/session/:sessionId` to end it. With no `--base-path`, the same routes sit at the root: `POST /session`, `GET /session/:sessionId/source`. Note the spelling of the route parameter while you are here — it is `:sessionId`. That default is behind the first mystery many teams hit when they point an older suite at a current server. The client still appends the historic `/wd/hub` an earlier Appium line used, the server has no route there, and the very first request dies before any device is touched. The symptom reads like "the server is down". The fix is to make the two ends agree: either start the server with `--base-path /wd/hub`, or drop the prefix from the client's URL. ## A worked pair for the watering-rota box Say the allotment watering-rota suite has an Android lane and an Apple lane, each with its own server: | | Android lane | Apple lane | |---|---|---| | driver that answers | UiAutomator2 | XCUITest | | server flags | `--port 4726 --base-path /wd/hub` | `--port 4727 --base-path /wd/hub` | | new session goes to | `POST /wd/hub/session` on port 4726 | `POST /wd/hub/session` on port 4727 | The point of the table is that only one thing differs, and it is the *port*, not anything mobile. Neither flag is platform-specific: the same port and prefix serve a session the Android UiAutomator2 driver answers and one the Apple XCUITest driver answers, and neither flag knows which driver will pick the session up. ## Ports do not multiplex; prefixes do A common wrong answer is that two servers can share a port so long as their base paths differ. They cannot. A TCP port is held by one listening process, and the second server fails to bind. The prefix is routing *inside* a listener, so it can separate two route sets in one process, never two processes. If a box must host two servers, each needs its own `--port`. The inverse confusion is just as common: assuming a second port implies a second base path. It does not. Two servers can use the same prefix on different ports, and that is usually the tidier arrangement, because then only one number varies between the lanes and a suite moving between boxes changes one field. ## Choosing values on purpose 1. **Set `--port` explicitly**, even to the value the default would have given you. It documents the box, and it survives a default moving under you. 2. **Set `--base-path` explicitly** and make the client's URL match. Pick one convention for the whole fleet so a suite can move between boxes without an edit. 3. **Set `--address` explicitly.** Binding loopback keeps the server unreachable from the network; binding a routable interface should be a decision, not an inherited default on a shared machine. ## What these flags do not touch They are core server plumbing and nothing more. They say nothing about which drivers the box has installed, which device a session lands on, what a driver puts on that device, or which ports a driver needs per session on the device side. A correct prefix and an open port still yield sessions that fail for entirely device-side reasons. The reverse is the useful diagnostic, though: a suite that never creates a session at all, and produces no device-side evidence to look at, is far more often a port or prefix mismatch than anything mobile. Check the address before you check the phone.

  • Two Appium servers must run on one unattended box. What has to differ?
    The port, at minimum. Two processes cannot listen on the same TCP port, and giving them different base paths does not change that — the prefix routes inside one listener rather than creating a second one. Give each server its own `--port` and keep the prefix identical, so only one number varies between the two lanes.
  • What breaks first if a suite keeps a `/wd/hub` prefix against a server started with no `--base-path`?
    The very first request. `POST /wd/hub/session` matches no route, so no session is ever created and the failure looks like the server being down rather than a path mismatch. Fix it at either end: start the server with `--base-path /wd/hub`, or drop the prefix from the client's URL.

saying these in an interview costs you the question

  • Thinks --base-path changes where driver or app files live on disk
  • Assumes /wd/hub is still the prefix a server uses by default
  • Says two servers can share a port when their base paths differ
  • Confuses the server's listening port with a per-session device port
  • Believes the base path applies only to the new-session route