Appium "Could not start the UiAutomator2 server" in CI

Appium installs two helper APKs (the UiAutomator2 server and its test package) and launches them via am instrument. If that instrumentation crashes or times out, session creation fails with "Could not start the uiautomator2 server".

What this error means

A new session fails with "Could not start the uiautomator2 server: The instrumentation process cannot be initialized" or "socket hang up" while the driver tries to reach the server on the device.

Appium

An unknown server-side error occurred while processing the command.
Original error: Could not start the uiautomator2 server: The instrumentation
process cannot be initialized within 30000ms timeout. Make sure the application
under test does not crash the instrumentation.

Common causes

A slow or overloaded emulator on CI

On a shared CI runner the emulator is slow, so the instrumentation process does not initialize within the timeout.

A stale or mismatched server APK

A leftover UiAutomator2 server from a prior run, or one built for a different driver version, fails to launch cleanly.

How to fix it

Force reinstall the helper apps and raise the timeout

Set uiautomator2ServerInstallTimeout and uiautomator2ServerLaunchTimeout higher for CI.
Enforce a clean reinstall of the server so a stale copy is discarded.
Re-run once the emulator is fully booted.

capabilities.json

{
  "appium:enforceAppInstall": true,
  "appium:uiautomator2ServerLaunchTimeout": 60000,
  "appium:uiautomator2ServerInstallTimeout": 60000
}

Ensure the emulator is warm first

Wait for sys.boot_completed before creating the session so instrumentation has a responsive device to launch on.

Terminal

adb shell 'while [[ -z $(getprop sys.boot_completed) ]]; do sleep 1; done'

How to prevent it

Raise UiAutomator2 server launch/install timeouts on CI hardware.
Boot and warm the emulator before requesting a session.
Uninstall leftover io.appium.uiautomator2.server* packages between runs.