Why does my local Appium execution fail with socket hang-up or session timeout?

Socket hang-up or session timeout errors usually occur when Appium is unable to start, continue, or cleanly close a device session.

This can happen due to one or more of the following reasons:

• The previous Appium session was not closed properly.

• The device is still locked or occupied by an earlier session.

• The same systemPort or related ports are being reused in parallel executions.

• The application is taking too long to install or launch.

• The CI/CD job stopped before the session cleanup was completed.

• Multiple jobs are trying to use the same device at the same time.

• Required waits or timeout configurations are missing or too low.

To reduce these failures:

1. Close the session properly

   • Always call driver.quit() at the end of execution.

   • Add cleanup handling in finally blocks wherever possible.

2. Avoid port conflicts

   • Do not reuse the same systemPort for parallel Android executions.

   • Assign unique ports when running multiple sessions.

3. Increase timeout values where required

   • Increase app launch or install timeout if the application takes longer to start.

   • Add proper waits before interacting with elements.

4. Avoid overlapping executions

   • Do not trigger multiple CI/CD jobs on the same device at the same time.

   • Ensure the previous job has completed and released the device before starting a new run.

5. Check device availability

   • Make sure the device is online, unlocked, and available before starting execution.

   • If the device was used in a previous failed run, wait for it to recover or reconnect.

If the issue occurs frequently, share the following details with TestGrid Support:

• Appium server logs

• Device name and OS version

• Execution timestamp

• TestGrid session ID, if available

• Desired capabilities used in the execution

• Error screenshot or screen recording, if available