skip to content

In Appium, what does the `--session-override` server flag do when a session is already open?

level: middleimportance: nice to knowfreq 28%

answer

  1. about a second session arriving
  2. clobbering, not queueing
  3. existing sessions deleted first
  4. all of them, not the matching one

basics

~20 s

With that flag set, a new session request first deletes every session the Appium server is already holding, then starts the requested one. Without it, the older session stays alive beside it and keeps its device busy.

solid answer

~40 s

`--session-override` changes what the server does when `POST /session` arrives while it already holds sessions: instead of adding one beside them, it deletes the existing ones first — running each one's ordinary teardown — and then creates the requested session. On an unattended box that is a recovery mechanism. A run killed mid-suite leaves a session that still holds the device, and the next run's first request clears it rather than fighting it. The cost is that the behaviour is indiscriminate: it deletes *every* session the server holds, so a box that deliberately runs several sessions at once must leave the flag off, because each new session would tear down its neighbours. Choosing it is really choosing whether the box is one lane or many.

go deeper

for a junior

Know that an Appium server can hold more than one session at a time, and that this flag makes a new session clear the existing ones instead of joining them.

for a middle

Explain that the delete happens at session-create time, that it covers every session the server holds rather than a matching one, and why that is useful recovery on a single-lane box.

for a senior

Be ready to argue where the flag is wrong: on a box running concurrent sessions it turns healthy workers into mid-run failures that look exactly like flakiness.

for a principal

Own the question underneath it — is this box one lane or many — and the cleanup policy that follows, whether a fresh server process per run or a clobbering flag, but not a habit of both.

## What a server does when a second session arrives An Appium server keeps a map of the sessions it currently owns. When `POST /session` arrives, the default behaviour is additive: the server creates the new session and the ones it already holds keep running. That is what lets a single server drive more than one device at a time, and it is the right default for a machine whose job is to serve several workers. It is the wrong default for a machine whose job is to run one suite to completion, unattended, over and over. There the interesting case is not "two runs on purpose" but "one run that died". A process killed mid-suite never sends its teardown, so the session it opened stays in the map, still holding the device it was driving. The next run then starts against a server that believes it is busy. ## What the flag changes `--session-override` changes the create path. With it set, an incoming `POST /session` first deletes the sessions the server already holds — running each driver's ordinary teardown — and only then creates the requested one. The old word for this is clobbering: a new session takes the box whether or not something was there. Two properties are worth stating precisely, because both are commonly mis-remembered: - It is **server-wide, not targeted.** It does not delete "the session on the same device" or "the session with matching capabilities". It deletes every session the server holds. - It is **a delete, not a reject.** The alternative is not the server queueing or refusing the second request; without the flag the older session simply carries on beside the new one. ## Why an unattended box wants it For an allotment watering-rota suite that runs on a schedule against one wired device, the flag buys recovery with nobody in the loop. Yesterday's run was killed with a session open; today's first request clears it and proceeds. The alternative is a box that needs a human to notice and restart the server, which is the one thing an unattended box exists to avoid. ## What an orphaned session is still holding Clearing the stale session matters more than "freeing a map entry", because a mobile session is not only bookkeeping — the driver put something on the device to serve it, and what that is differs by platform: | | Android lane | Apple lane | |---|---|---| | what the driver started | the UiAutomator2 driver's on-device helper server | WebDriverAgent, installed and running on the device | | what an orphan keeps alive | that helper server, and the driver's device connection | the agent process, and the port it is bound to | | what a clean delete does | runs the driver's teardown and releases them | runs the driver's teardown and releases them | Teardown is what stops the on-device agent, and this flag is what makes teardown happen for a session that nobody is going to delete politely. ## Where the flag is exactly wrong On a box that deliberately runs several sessions at once, `--session-override` is destructive. Worker two starts, deletes worker one's session, and worker one fails on its next command; worker three then does the same to worker two. The failures look like flakiness — commands failing mid-run on a session that was healthy a second earlier — and the cause is a server flag rather than the app or the device. So the decision is not really about the flag; it is about what the box is: 1. **One lane, one session at a time.** Set it. Orphan recovery is free and there is nothing to clobber. 2. **Several sessions on purpose.** Leave it off, and clear stale sessions another way — a fresh server process per run is the bluntest and most reliable version. 3. **Unsure.** Treat unsure as several. An accidental second session that dies is cheaper than a deliberate second session that gets killed. ## Reading the symptom If a box has the flag on when you did not expect it, the tell is the pairing: a run fails because its session has vanished, at the same moment another run started. If the box has it off when you expected it on, the tell is the opposite: the new run cannot get the device because the previous run's session still owns it. Both are configuration symptoms, and both are answered by reading the line the server was started with rather than by re-reading the suite. That is the general lesson of the server flag set: some failures that look like test flakiness are decisions somebody made once, on a command line, on a machine nobody has logged into in weeks. ## What it does not do The flag has nothing to say about a session that is alive but idle, about a device that has hung, or about state a previous run left inside the app. It acts once, at the moment a new session is requested, and its only lever is deleting what the server currently holds.

  • Your unattended box runs three concurrent sessions. Would you set `--session-override`?
    No. The flag deletes every session the server holds whenever a new one starts, so the second and third workers would kill each other's sessions and the failures would read as flakiness. It suits a box that runs one session at a time and needs to survive an orphan; a multi-session box has to clear stale sessions another way.
  • What is left on the device after the flag clears an orphaned session?
    Less than you might fear: deleting a session runs the driver's own teardown, so the Android UiAutomator2 helper server and the Apple WebDriverAgent process are stopped the ordinary way rather than orphaned further. What the flag cannot undo is anything the dead run wrote — the app's own stored state on the device is untouched by session deletion.

saying these in an interview costs you the question

  • Thinks it makes the server reject the second session instead
  • Says it only replaces a session on the same device
  • Believes the flag is required for parallel runs
  • Assumes it recovers a hung device rather than a stale session
  • Treats it as an idle-session timeout under another name