In Appium, why does a local appium:app path fail once the server URL is remote?

## Capabilities are data, not instructions your machine executes A capability set is JSON. The client serialises it, sends it in `POST /session`, and then stops being involved: the server deserialises it and hands it to a driver, which runs inside the server process on the server's machine. Every side effect a capability has — installing a build, launching an agent, writing an artefact — happens *there*. Once that is clear, the behaviour of path-valued capabilities stops being surprising and becomes the only thing that could possibly happen. So `appium:app` set to a path on the machine running your tests is, from the server's point of view, an arbitrary string. It will try to open it on its own filesystem, find nothing, and fail. Nothing was transmitted, because nothing in the protocol says a capability value is a file to upload. ## Which capabilities this rule covers Any capability whose value is a path is resolved server-side. Examples, each attributed to the platform whose driver reads it: - `appium:app` — the build to put on the target; read on the server host on both Android and Apple platforms. - Android's `appium:chromedriverExecutable` — a binary path on the server host. - Android's `appium:keystorePath` — a signing keystore on the server host. - iOS's `appium:derivedDataPath` — a build-output directory on the server host. The list is not the point; the rule is. If a value looks like a path, ask whose filesystem it is a path *on*, and the answer is always the server's. ## Three ways to fix it 1. **Hand the server a URL instead of a path.** Give `appium:app` an `http(s)` URL and the server fetches the artefact itself. The capability name is unchanged; only the form of the value differs. 2. **Name a build that is already there.** If the target already carries the build, you do not need an artefact capability at all: identify it instead, with Android's `appium:appPackage` or iOS's `appium:bundleId`. 3. **Put the artefact where the server can see it.** A path is perfectly fine when it is a path *on the server host* — the mistake is only ever assuming that your paths and the server's are one namespace. ## The diagnostic signature | What you see | What it means | |---|---| | An error naming a path you can open locally | The server tried your string on its own filesystem | | A 404 or connection error at the handshake | The endpoint is wrong; the capability was never read | | The build installs but is the wrong version | The server resolved a path or URL of its own, just not the one you meant | The first row is the signature of this specific mistake, and it is unusually easy to misread, because the path in the message is one you can verify exists — on the wrong machine. Reading the error as "the file is missing" sends people to check their own disk, where the file is exactly where they left it. ## Why the capability names do not change It is worth stressing what stays fixed, because the instinct on hitting this is to hunt for a remote-specific capability. There is none. The Android and iOS capability sets are identical against a local and a remote endpoint: the same names, the same prefixing rules, the same driver selection. Only the *value* of a path-valued key has to be reachable from where the driver runs. Treating this as a value problem rather than a schema problem keeps a suite honest — you end up with one capability builder per platform, parameterised by an artefact location, instead of a local branch and a remote branch that drift apart. ## How this shows up in practice - A suite is developed against a server on the same machine, where every path resolves by accident, and then breaks the first time it is pointed elsewhere. - A build is published to a location the server can fetch, and the capability quietly becomes a URL, which then works in both directions — a server on your own machine can fetch a URL too. - A signing or build-output path is copied from a colleague's configuration and refers to a directory that exists only on their machine, which is the same bug wearing different clothes. ## The habit worth forming When a capability's value is anything that looks like a filename, a directory or an executable, write down which host it lives on before you write the capability. If the answer is "mine", the suite is only ever going to work while the server is also mine. Making artefact location an explicit, environment-supplied input — a URL by preference — is what lets the same Android and iOS capability sets run unchanged against any endpoint, which is the whole reason the client can be nothing more than a URL in the first place.