How to Fix Cypress "The Chromium Renderer process just crashed"

TL;DR

Run the failing spec alone with an explicit browser, then check Docker shared memory, CI resource contention, spec length, and Cypress release history. Verify the fix under the original CI workload.

Key Takeaways

• Reproduce the crash in one spec with an explicit browser before changing settings.
• Inspect Docker /dev/shm and container memory when crashes occur only in containers.
• Split long specs and verify current Chromium memory-management settings.
• Budget CI RAM and CPU for every concurrent browser plus the application.
• Compare Cypress release notes when the crash begins after an upgrade.
• Verify the original workload and browser after the focused fix passes.

If you need to fix Cypress Chromium Renderer process crashed, start by identifying whether the failure happens in one test, late in a long spec, or only inside CI or Docker. Cypress reports it when the Chromium tab running your application dies before the spec finishes; the message alone does not identify why.

We detected that the Chromium Renderer process just crashed.

Recent Chrome runs can say We detected that the Chrome Renderer process just crashed. The wording differs by browser and Cypress release, but the investigation is the same. Preserve the failing spec name, browser, Cypress version, run mode, and preceding system logs before changing configuration.

TL;DR

1. Reproduce one affected spec: npx cypress run --browser chrome --spec 'cypress/e2e/checkout.cy.ts'. Replace the path with your actual spec.
2. If the job is containerized, inspect df -h /dev/shm and rerun with a larger shared-memory allocation, such as Docker's --shm-size=1g.
3. If a long spec dies late, split it and check manageBrowserMemory. In Cypress 16 and later, that option is on by default for Chromium; do not copy old advice to enable experimentalMemoryManagement without checking your installed version.
4. If several CI workers fail together, give each browser enough CPU and RAM or lower concurrency. Cypress documents at least two CPUs and 4 GB RAM for CI, with 8 GB or more recommended for long runs or video.
5. Check the Cypress changelog if the crash began after an upgrade. A documented message-related renderer leak and two other crash contributors were fixed in 15.19.0.

What the Error Actually Means

Chromium separates the page renderer from the browser process. Cypress drives a browser, loads your app in a tab, and observes that renderer through its test runner. When the renderer exits, the current spec cannot safely continue. A failed cy.get() assertion or a server response with status 500 is a normal test failure; a dead renderer is a process failure. Retrying an assertion cannot revive that process.

The renderer can die because the operating system kills it for memory pressure, a container runs out of shared memory, the app allocates or loops indefinitely, a browser or GPU path fails, or Cypress itself has a regression. The official error guide lists resource starvation, memory-heavy apps, GPU trouble, browser bugs, and Cypress leaks as possibilities. Those are hypotheses, not a diagnosis for your run.

First capture a reproducible baseline. Run npx cypress --version and npx cypress info; record the exact browser selected. cypress run may use Electron when you did not explicitly choose Chrome. Then run the failing spec alone, using the browser reported by the failing CI job. A pass in a different browser is useful evidence, but it does not prove the original defect is fixed. For a focused walkthrough of the runner and browser selection, see the Cypress tutorial for beginners.

Root-Cause Decision Table

Treat the table as a branching plan. Change one variable per experiment, then rerun the original case. If you change memory allocation, browser, test structure, and Cypress release at once, a green run cannot tell you which change mattered.

1. Fix Cypress Chromium Renderer Process Crashed in Docker Shared Memory

Docker commonly starts containers with a small /dev/shm mount. Chromium uses shared memory for renderer work, so the browser can fail even while the host appears to have free RAM. This is particularly plausible when the test passes on the host and fails in a container using the same code and browser. The Cypress Docker issue discussing shared memory documents this failure mode.

Inspect both the mount size and the container's overall limit. Run the first command inside the failing container, or use docker exec with its container ID. A nearly full /dev/shm is stronger evidence than a generic renderer message.

df -h /dev/shm
cat /sys/fs/cgroup/memory.max 2>/dev/null || true

Give a local Docker run more shared memory. Replace the image tag with a published cypress/browsers tag matching the Node and browser versions your project uses. Install the project's locked dependencies inside the container; the browsers image supplies browsers and system libraries, while your project supplies its Cypress package.

docker run --rm --shm-size=1g -v "$PWD:/e2e" -w /e2e   cypress/browsers:<your-published-tag>   sh -lc "npm ci && npx cypress run --browser chrome --spec 'cypress/e2e/checkout.cy.ts'"

Verify: Run the original Docker command and the adjusted command against the same spec. Inside the adjusted container, df -h /dev/shm should show the new allocation. A completed run is the outcome that matters; a larger mount alone is not proof. In Compose, set shm_size: 1gb on the Cypress service and verify from inside that service. Keep the memory size a measured setting, since it consumes host resources. Avoid reaching immediately for --disable-dev-shm-usage; moving the pressure elsewhere can conceal a small container budget.

2. Fix Cypress Chromium Renderer Process Crashed in Long Specs

A spec that works when short but dies after dozens of tests often carries too much state in one renderer lifetime. Cypress keeps command data, the app may retain listeners, and large network responses can add pressure. The Cypress CI FAQ recommends splitting long-running specs, generally aiming for specs that run in under a minute. That is a diagnostic target, not a guaranteed crash threshold.

Use --spec to establish whether each half completes. First make two coherent files such as checkout-cart.cy.ts and checkout-payment.cy.ts; move independent tests with their setup rather than splitting inside a transaction just to hit a file count. Each file should create its own state or use a controlled fixture. That prevents a pass caused by accidental ordering. Run them separately:

npx cypress run --browser chrome --spec 'cypress/e2e/checkout-cart.cy.ts'
npx cypress run --browser chrome --spec 'cypress/e2e/checkout-payment.cy.ts'

Inspect manageBrowserMemory for your installed release. The configuration reference says it defaults to true starting in Cypress 16 and applies to Chromium-based browsers. If your configuration explicitly disables it on a supported release, remove that override or set it to true:

// cypress.config.ts
import { defineConfig } from 'cypress'

export default defineConfig({
  manageBrowserMemory: true,
  e2e: {},
})

Merge this setting into your existing config; preserve your real e2e, baseUrl, and setupNodeEvents settings. On an older release, check that release's configuration reference before adding an option it may not support. Verify: Run npx cypress run --browser chrome --spec 'cypress/e2e/checkout-cart.cy.ts,cypress/e2e/checkout-payment.cy.ts' and confirm both specs complete. Compare peak memory and duration across repeated runs. For structuring focused specs without hidden state, see Cypress test isolation for multi-user workflows.

3. Reduce Snapshot Retention in cypress open

numTestsKeptInMemory controls how many tests' snapshots and command data Cypress retains. The current documented defaults are 50 in cypress open and zero in cypress run. That distinction matters: setting it to zero in CI often changes nothing because run mode already uses zero. It is most useful when the interactive runner gets slower, freezes, or crashes after repeatedly running a suite.

Set a small value in the existing config and reopen the project. Zero is reasonable when you only need to inspect the current test; choose a higher number if you rely on earlier test snapshots while debugging. This affects the Cypress runner's retained history, not the application's own heap.

// cypress.config.ts
import { defineConfig } from 'cypress'

export default defineConfig({
  numTestsKeptInMemory: 0,
  e2e: {},
})

If you also use manageBrowserMemory, put both properties in one exported defineConfig object instead of replacing your config with separate examples. The setting can also be tested without editing a file:

npx cypress open --config numTestsKeptInMemory=0

Verify: Open the previously problematic spec, repeat the same sequence of tests, and watch whether the browser remains responsive. The command log will not retain earlier snapshots at zero. If the first test crashes before any history accumulates, snapshot retention is probably unrelated; continue with the app and browser branches. The Cypress configuration reference gives the mode-specific defaults.

4. Give Each CI Browser a Real Resource Budget

A runner advertised as having enough memory can still overcommit when it builds the app, starts a database, records video, and launches several browsers simultaneously. The browser's renderer competes with every other process on that machine. A failure clustered at the moment parallel jobs start points toward aggregate pressure, even if any one spec passes alone.

Measure the process environment before raising limits. On Linux CI, these commands show available memory, CPU count, and any cgroup cap visible to the job:

free -h
nproc
cat /sys/fs/cgroup/memory.max 2>/dev/null || true

Run one Cypress process as a control, then restore your usual concurrency. In a CI shell step that already builds and serves the app, the control command is:

npx cypress run --browser chrome --spec 'cypress/e2e/checkout.cy.ts'

Verify: Repeat the same spec on the same runner with one browser, then under normal parallel load. If only the parallel attempt crashes and available memory falls sharply, reduce simultaneous jobs or move to a larger runner. Cypress's installation guide lists at least two CPUs and 4 GB RAM for CI, with 8 GB or more recommended for long runs or video. Allocate for the application server and database too; a four-gigabyte job running several heavy services has less than four gigabytes available to Chromium.

Do not use a test retry as the primary fix. A retry can pass when the competing processes have finished, hiding an underprovisioned job and wasting CI time. Record a before/after run under realistic concurrency. For how to divide tests across workers without multiplying machine pressure unexpectedly, read Cypress parallelization.

5. Check for a Cypress Renderer Regression

A cleanly reproducible crash after a Cypress upgrade deserves a release-history check. The 15.19.0 changelog documents fixes for a ResizeObserver-related renderer crash, a per-message browser-memory leak in long command- or network-heavy specs, and memory retained by repeated cy.press() calls. These are specific cases; do not assume every renderer crash on an earlier release has that cause.

Capture your installed package and binary versions. npm ls cypress shows the dependency selected by the lockfile; npx cypress --version shows the package and binary information. Then compare the symptom with the changelog and upgrade through your normal dependency process to a release that includes the relevant fix. Keep the package-lock change in review so CI installs the same build.

npm ls cypress
npx cypress --version
npx cypress info

For a controlled upgrade, choose an actual published release compatible with your Node version, substitute it below, and commit the resulting lockfile:

npm install --save-dev cypress@<published-cypress-version>
npx cypress verify
npx cypress run --browser chrome --spec 'cypress/e2e/checkout.cy.ts'

The version placeholder is deliberate; copying a guessed package pin into production is worse than checking the release notes. Verify: Run the same spec, browser, machine class, and workload before and after the upgrade. If a minimal reproduction still fails on the newer release, keep the reproduction and full logs for a Cypress issue. Also compare browser versions, since an image update can change Chrome while the cypress npm package remains unchanged.

6. Remove Application-Side Loops and Retained State

A single page that crashes even when isolated can be exhausting the renderer independently of Cypress. Examples include a ResizeObserver callback that repeatedly changes an observed element, an unbounded DOM list, recursive state updates, or listeners and timers that survive navigation. A renderer crash on one route with ample container memory is a reason to inspect the app, not to keep increasing runner size.

First prove that the simplest visit is enough to reproduce the problem. Add a temporary focused Cypress spec. Replace the path with the failing route. This uses actual Cypress commands and gives you a small, shareable reproduction:

// cypress/e2e/renderer-repro.cy.ts
describe('renderer reproduction', () => {
  it('loads the affected page', () => {
    cy.visit('/checkout')
    cy.get('body').should('be.visible')
  })
})

Run it against your already running app, with your project's baseUrl configured:

npx cypress run --browser chrome --spec 'cypress/e2e/renderer-repro.cy.ts'

If the minimal visit crashes, load the same route in normal Chrome and inspect Chrome Task Manager or DevTools Memory. Watch whether the tab's memory grows while the page is idle. Disable one expensive feature at a time in the application, such as an auto-refresh poll or infinite list, and repeat the isolated spec. If the page is stable until a specific test command, inspect that action and the payload it loads. A huge intercepted response or repeated full-page rendering can matter more than the number of tests.

Verify: The minimal spec should complete repeatedly, and the page's renderer memory should stop climbing under the same interaction. Preserve an assertion on the intended behavior, not merely cy.visit(), when moving the reproduction into your permanent suite. If you use network stubs to isolate large responses, review Cypress network stubbing so the stub does not accidentally hide the production behavior you need to test.

7. Isolate Browser and GPU-Specific Failures

If Chrome fails while another browser runs the same isolated spec, investigate the browser build, graphics stack, launch arguments, and enterprise policy. Browser switching is a diagnostic comparison, not proof that your users' Chrome path works. Cypress's launching browsers guide documents --browser and the difference between headless and headed runs.

Start with detected browsers and repeat the identical spec in Chrome and Firefox if both are installed. Firefox has a different renderer architecture, so a Firefox pass narrows the search but does not pinpoint the cause. Then compare headed and headless Chrome on the same machine:

npx cypress info
npx cypress run --browser chrome --spec 'cypress/e2e/checkout.cy.ts'
npx cypress run --browser firefox --spec 'cypress/e2e/checkout.cy.ts'
npx cypress run --headed --browser chrome --spec 'cypress/e2e/checkout.cy.ts'

Verify: Record which exact combination fails. If only one managed Chrome installation fails, inspect chrome://policy, GPU driver logs, and custom before:browser:launch arguments. Remove custom launch arguments temporarily and rerun before adding new ones. If all browsers fail on the same route, return to the app or host-memory branch. Do not insert broad --no-sandbox or GPU-disabling flags into CI as a generic cure; each flag changes security or rendering behavior and needs evidence from the affected environment. The Cypress troubleshooting reference explains browser detection and launch diagnostics.

How to Verify the Fix

Verification should reproduce the original load, not just turn one red run green. Capture the pre-fix command and environment: spec path, browser name and version, Cypress package and binary, CI machine or Docker image, number of concurrent workers, and whether video was enabled. Note where in the spec the crash occurred. A crash at the same test every time suggests a different branch from one that moves around under load.

Run the focused case first. Then run its surrounding spec group and finally the full CI job using normal concurrency. If the issue was intermittent, repeat enough runs to observe the former failure pattern; three clean runs are useful evidence but not a statistical guarantee. Keep the outcome of each attempt, including duration and memory observations. For Docker, record /dev/shm capacity before and after. For CI, record peak memory and the number of active browser processes.

npx cypress --version
npx cypress info
npx cypress run --browser chrome --spec 'cypress/e2e/checkout.cy.ts'

A passing single spec with a lower worker count verifies only that configuration. Restore the intended worker count and verify again before declaring the pipeline fixed. A Firefox pass does not substitute for a Chrome pass if Chrome is the required target. A browser that stays alive while assertions fail has moved you from process diagnosis to ordinary test debugging, which is useful progress. The Cypress guide to debugging a failing test can help with that next step.

Prevent It From Coming Back

Keep Cypress and browser versions pinned through your lockfile and container image tag. Review the Cypress changelog whenever either changes. A short, reproducible smoke spec can reveal a browser regression before the full suite becomes unreliable. Track which CI runner size and concurrency settings produce stable results instead of copying them from another repository.

Split specs by user behavior and setup cost. Avoid a single file that accumulates every checkout, search, and account scenario. Use fresh state per test or suite where practical, and confirm tests pass in isolation. When a feature introduces large tables, charts, canvas work, or continuous observers, run its browser test under the same CI resources used for the rest of the project. A fast laptop may hide the pressure of a small hosted runner.

Keep diagnostics cheap to obtain. Save Cypress terminal output, the failed spec name, and resource metrics from failed jobs. Enable screenshots and video where they help reveal the last visible action, while recognizing that video recording also uses resources. A failure report with browser version, memory ceiling, /dev/shm size, and a one-spec reproduction is far more actionable than a screenshot of the renderer message alone. For suite reliability practices, see Cypress handling flaky tests.

Interview Questions and Answers

Q: What is the first distinction to make after a Cypress renderer crash? Determine whether the failure follows one page or grows with run duration. A single-page reproduction favors app or browser behavior; a late, shifting failure favors resource pressure or retained state.

Q: Why can Docker crash when the host has free RAM? The container can have a constrained /dev/shm mount or cgroup memory limit. Chromium needs both ordinary memory and shared memory, so inspect the container's view rather than only the host dashboard.

Q: Why does changing numTestsKeptInMemory sometimes have no effect in CI? Run mode already defaults to zero. The option primarily reduces snapshots retained in open mode; a CI crash may require a shorter spec, more resources, or an app fix.

Q: What does manageBrowserMemory do? On supported Chromium runs, Cypress samples browser memory and collects garbage between tests when pressure crosses its threshold. It does not cure an infinite loop or a page that exhausts memory inside one test.

Q: How would you prove a Cypress regression? Keep app code and browser constant, reproduce on one Cypress release, and compare with a release containing a documented fix. Provide the spec, versions, logs, and environment details with the report.

Q: Why is a retry a weak fix? It can pass after competing jobs finish or after a process restarts, while the original memory pressure remains. Use retries to quantify flakiness, then correct the condition that killed the renderer.

Common Mistakes

• Treating the crash text as proof of a Cypress bug. It reports a dead renderer, not the cause.
• Enabling the legacy experimentalMemoryManagement setting from an old post without checking the installed release. Current documentation describes manageBrowserMemory and its version-dependent default.
• Raising numTestsKeptInMemory during debugging and forgetting that open mode retains more snapshots as a result.
• Setting a very large Docker shared-memory mount without checking the host's actual RAM and other containers.
• Changing --browser during diagnosis and then declaring a Chrome issue solved because Firefox passes.
• Masking an app loop with test retries, longer timeouts, or disabled assertions. None restores a dead renderer.
• Removing video, splitting specs, upgrading Cypress, and enlarging CI in one commit. Without isolated experiments, the fix cannot be explained or maintained.

Conclusion

To fix Cypress Chromium Renderer process crashed, reproduce one spec with an explicit browser, inspect the environment that ran it, and follow the symptom to its likely cause. Increase Docker shared memory when it is constrained, budget CI resources for concurrent browsers, split long specs, check current memory-management settings, and compare against documented Cypress fixes. Finish by rerunning the original CI workload with the same browser and concurrency that failed.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Fix "Cypress failed to start" and cypress verify Errors
• How to Fix "The Cypress binary is missing" in CI
• How to Fix Appium "The instrumentation process is not running"
• How to Fix Cypress "cy.visit() failed trying to load"
• How to Fix "Playwright Test did not expect test() to be called here"
• How to Fix Appium WebDriverAgent Failed to Start on iOS