## TL;DR
Cypress lost its automation connection to the browser, which almost always means the browser process died: out of memory in a small CI container, a GPU process crash, or the browser being killed by the environment. The spec is usually innocent. Rerun with debug logging to capture the browser's death signature, check memory pressure, disable the GPU, and only then look at the spec.

## The query
```text
cypress The automation client disconnected flake in CI  -  how to debug
```

## Use this when
- The automation client disconnected appears intermittently in CI
- the disconnect moves between specs from run to run
- the CI job runs in a container with limited memory

## Not for
- the disconnect happens on the same spec every time (that spec is doing something fatal; debug the spec)
- the error is a proxy or network error rather than a browser death
- Cypress cannot start at all (that is an install or display problem)

## Steps

### 1. Rerun with Cypress debug logging enabled
The debug log captures what the browser was doing when the connection dropped. Run one affected spec with it on.
```bash
DEBUG=cypress:* npx cypress run --spec cypress/e2e/flaky.cy.js 2>&1 | tail -60
```
Expected output: the log shows the disconnect and whatever the browser logged just before it (often a crash or OOM line).

### 2. Check memory pressure in the CI container
Compare the container's memory limit against what the browser needs. Chrome with a Cypress-run page easily wants 2 GB.
```bash
cat /sys/fs/cgroup/memory.max 2>/dev/null || cat /sys/fs/cgroup/memory/memory.limit_in_bytes
free -m
```
Expected output: you know the real memory ceiling; a limit near or under 2 GB explains the flake.

### 3. Disable the GPU and reduce in-memory state
The GPU process is a frequent crash source in headless CI, and Cypress keeps test state in memory between specs.
```js
// cypress.config.js
module.exports = defineConfig({
  e2e: {
    // limit retained state
  },
});
```
```bash
npx cypress run --browser chrome -- --disable-gpu
```
Expected output: the browser launches with software rendering and the disconnect stops recurring.

### 4. Pin the browser version for reproducibility
An auto-updating browser changes the failure surface under you. Pin the browser in the CI image or the Cypress config so the fix stays fixed.
```bash
npx cypress info | grep -A2 "Browser"
```
Expected output: every CI run uses the same browser build and the flake stays gone.

## Tool compatibility
- Cypress 10 - 14
- Chrome / Edge / Electron in headless CI

## Variant phrasings
- The automation client disconnected flake in CI
- cypress browser disconnected intermittently
- Cypress verification timed out after browser crash

## Why it happens
Cypress drives the browser over an automation protocol, and if the browser process dies the protocol has nothing to talk to. In CI the usual killer is memory: containers default to small limits, Chrome's renderer plus GPU plus Cypress's own process exceed them, and the OOM killer takes the browser. The disconnect message is the symptom; the dead browser is the cause.

## Edge cases / pitfalls
- docker's default /dev/shm is 64 MB and Chrome wants much more; pass --disable-dev-shm-usage to the browser flags
- numTestsKeptInMemory and aggressive video settings raise memory; trim them before raising container limits
- antivirus or security agents on self-hosted runners sometimes kill the browser; check their logs when cloud CI is clean
- a disconnect that follows a specific cy.visit() to a heavy page is a page-weight problem; that page needs a diet, not the config

## Provenance

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