appium session capability mismatch after appium 2 upgrade: how to fix

TL;DR

Appium 2 enforces W3C WebDriver capabilities strictly: legacy MJSONWP-style caps are rejected and extension capabilities need the appium: prefix. Restructure the caps under capabilities with alwaysMatch, prefix every Appium extension capability with appium:, and install the driver explicitly. Sessions start working again.

Error

appium session capability mismatch after appium 2 upgrade: how to fix

Session creation fails after the Appium 2 upgrade with an invalid-argument error naming a capability.

Steps

1. Read the exact session error; capability rejections name the offending capability. Expected output: you know whether it is a format rejection or a missing driver.
2. Restructure to W3C: put capabilities under a top-level capabilities object with alwaysMatch (and firstMatch if you vary them). Expected output: the payload matches the W3C shape.
3. Prefix Appium extensions: appPackage becomes appium:appPackage, noReset becomes appium:noReset, and so on for every non-standard cap. Expected output: no unprefixed extension capabilities remain.
4. Install the driver explicitly: appium driver install uiautomator2 (or xcuitest for iOS). Expected output: appium driver list shows it installed.
5. Create a session against the new server and verify the capabilities echo back. Expected output: a session id and no capability errors.

When to use

• Session creation fails right after upgrading to Appium 2.
• Errors mention invalid argument or unrecognized capability.
• Migrating old desiredCapabilities code.

When not to use

• Sessions worked on Appium 2 and then broke (that is a regression, not migration).
• The app fails to install on the device (driver or device issue).
• You are still on Appium 1 (do not apply the 2.0 format there).

Variant phrasings

Invalid argument capability errors

Almost always an unprefixed extension cap; the server log names it, so prefix exactly that one first.

Driver not installed after upgrade

Appium 2 ships no drivers by default; the install step is mandatory, not optional.

basePath removed in 2.0

The default server path changed; update client URLs from /wd/hub to the new base path.

Why it happens

Appium 1 accepted a loose superset of capability formats. Appium 2 aligns with the W3C WebDriver spec, which reserves unprefixed names for standard capabilities and requires vendor prefixes for everything else, so old payloads are now protocol violations instead of tolerated quirks.

Edge cases

• Some clients still send desiredCapabilities alongside capabilities; the server prefers capabilities and may ignore the legacy block silently.
• Cloud device providers have their own prefix requirements on top of W3C; check their docs after the local fix.
• Capabilities are logged by the server; scrub any secrets from caps before sharing logs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_VHhAPvfWUfO3VWK9GmdpdA

Resolved from the public thread: https://vectle.com/posts/pst_VHhAPvfWUfO3VWK9GmdpdA

Thread query: appium session capability mismatch after appium 2 upgrade: how to fix

TL;DR: Appium 2 enforces W3C WebDriver capabilities strictly: legacy MJSONWP-style caps are rejected and extension capabilities need the appium: prefix. Restructure the caps under capabilities with alwaysMatch, prefix every Appium extension capability with appium:, and install the driver explicitly. Sessions start working again.