How to Fix Cypress Retries That Make Tests Pass Despite Failures
A Cypress test that passes on retry can still be flaky. Learn how retries work, how to inspect the first failure, and how to fix the underlying cause.

A Cypress test that fails once and passes on a retry is still flaky. By default, Cypress stops retrying when an attempt passes, so the overall test can end as passed even though an earlier attempt exposed a real failure. Treat retries as a limited CI safety net: inspect the failed attempt, correct the synchronization or setup problem, and use a small, intentional retry allowance. If a recovered failure must continue to fail the build, review Cypress’s experimental retry strategies and confirm they are supported by your installed version.
This guide covers test retries, which rerun a whole test, and retry-ability, which repeats linked queries and assertions while Cypress waits for application state. They solve different problems. See Cypress’s test retries guide and retry-ability guide.
1. Understand why a retry can hide a failure
With standard test retries, Cypress runs the test again after a failure, up to the configured number of additional attempts. If a later attempt passes, Cypress stops and the test’s final result can be passing. The failed attempt still matters: it is evidence the test or the conditions it depends on are unstable. Cypress explicitly notes that a test can pass after retries and still be flaky (Cypress Cloud flaky test management).
A retry count is the number of attempts after the original attempt. For example, retries: 2 allows up to three total attempts. Each retry re-executes the entire test and its beforeEach and afterEach hooks. Failures in before or after hooks do not trigger a test retry. Retrying therefore affects both the reliability signal and suite duration (Cypress test performance).
2. Distinguish test retries from retry-ability
| Mechanism | What runs again | How to configure or use it |
|---|---|---|
| Test retries | The failed test, including per-test hooks | retries in config or a suite/test override |
| Retry-ability | Linked Cypress queries and assertions, while waiting for them to pass or time out | Use queries and meaningful assertions such as .should() |
Queries and assertions linked in a chain retry together. Non-query commands such as actions execute once; a later assertion retry does not cause a preceding .click() to be issued repeatedly. Do not use test retries to compensate for an assertion that checks the wrong condition or runs before the application is ready.

A .should() partway through a longer query chain can form a retry boundary: after it passes, Cypress locks the subject, and later queries retry from that subject. If the application re-renders and detaches the element, query again from a stable selector rather than continuing to rely on a stale DOM subject. See the retry-ability guide.
3. Configure a small, deliberate retry allowance
By default, Cypress configures zero retries for both run and open modes. You can set separate values globally, then override them for a suite or individual test. This example allows one extra attempt in CI-style cypress run and none in interactive cypress open:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
retries: {
runMode: 1,
openMode: 0,
},
})
For TypeScript, use the same configuration in cypress.config.ts:
import { defineConfig } from 'cypress'
export default defineConfig({
retries: {
runMode: 1,
openMode: 0,
},
})
Choose values based on how quickly developers need local feedback and how much transient CI instability the team is willing to tolerate. One retry is an example, not a universal setting. A value of zero exposes the first failure immediately; larger values permit more recovery attempts, add more runtime, and can make a flaky suite appear green more often.
You can scope retries to a suite or a test as well:
describe('checkout', { retries: 1 }, () => {
it('submits a valid order', { retries: 2 }, () => {
cy.visit('/checkout')
cy.get('[data-testid="submit-order"]').click()
cy.get('[data-testid="order-confirmation"]')
.should('be.visible')
})
})
Use a local override only when the test has a clear reason for it. A broad retry count can multiply the extra work across a large suite. The configuration reference documents retry settings and defaults.
4. Fix the underlying failure
- Start with the first failed attempt. Record the failing command, assertion, error and attempt number. In Cypress open, inspect the Command Log; for recorded runs, Cypress Cloud can show retry history and failed-attempt artifacts, subject to current product details.
- Wait for application state, not elapsed time. Assert on the UI or wait for the relevant request before continuing. A meaningful assertion lets Cypress retry the linked query while the application reaches the expected state.
- Check the condition you actually need. Confirm that the assertion verifies the state required by the next step, rather than merely checking that an element exists when it is still loading, disabled or showing stale data.
- Investigate unstable dependencies. Check API responses, service or database availability, test data collisions, network conditions and other dependencies. Cypress identifies insufficient assertions around actions or network requests as a common source of flakiness (Cypress debugging guide).
- Make setup safe to repeat. A retried test runs
beforeEachandafterEachagain. Ensure setup and cleanup tolerate repeated execution and do not rely on residue from a prior attempt. This is a practical implication of the hook behavior; verify it against your test data and setup. - Re-query after re-renders. If a UI update replaces an element, start again from a stable selector so Cypress can find the current DOM node.
- Keep a record of recovered failures. Track tests that fail and later pass as flaky, rather than counting only final passes. Cypress Cloud documents flaky-test filters and test history for recorded runs; confirm current feature availability and plan eligibility before relying on it.
A fixed delay such as cy.wait(2000) does not establish that the required state is ready. Prefer a state assertion or a wait tied to a specific request. Cypress’s debugging guide observes that flaky tests often lack enough assertions around actions or network requests before moving on.

5. Use timeouts for slow conditions, not as a blanket cure
Command timeouts affect retry-ability; they do not change how many times Cypress reruns a failed test. The documented default defaultCommandTimeout is 4,000 milliseconds. When one operation legitimately takes longer, set a timeout on that command and retain an assertion for the desired result:
cy.get('[data-testid="mobile-nav"]', { timeout: 10000 })
.should('be.visible')
.and('contain', 'Home')
First check that the test is waiting for the right condition. Increasing the global timeout can slow many failing commands and does not fix a missing or incorrect assertion. Cypress also documents timeout 0 for disabling retrying on a query when an immediate synchronous check is intended. See the retry-ability guide.
6. Choose whether a recovered failure should fail CI
Standard retries favor a passing final result when an attempt recovers. Cypress also documents experimental retry strategies: detect-flake-and-pass-on-threshold requires a configured number of passing attempts for a passing result, while detect-flake-but-always-fail treats a test that exhibits flakiness as failed. Their options include maximum retries, required passes and whether to stop retrying after a pass.
These strategies are experimental and version-sensitive. Cypress’s configuration reference says they are available from Cypress 13.4.0. Check the current experimental features guide and configuration reference against the version installed in your project before adopting them. Consider the trade-offs:
| Question | What to decide |
|---|---|
| Failure visibility | Should a test that fails once and passes later finish green, or remain a failure? |
| Execution cost | How many full test and hook executions can CI afford? |
| Developer feedback | Should local interactive runs stop immediately while CI receives a limited retry? |
| Version stability | Does the installed Cypress version support the experimental behavior you intend to configure? |
7. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Test is green, but Cypress shows an earlier failure | A later standard retry passed | Inspect and record the failed attempt; fix the flaky condition and track recovered failures separately. |
| Element is missing only on the first attempt | The test moved on before the UI or request reached the expected state | Assert on a meaningful UI condition or wait for the specific request; avoid arbitrary sleeps. |
| “Detached from the DOM” or stale element errors | A mid-chain assertion passed, then the application re-rendered and replaced the subject | Re-query from a stable selector after the update; restructure the chain around the expected state. |
| Action appears to happen only once despite retries | Retry-ability repeats linked queries and assertions, not non-query commands such as clicks | Assert on the post-action result; do not expect a later assertion retry to repeat the action. |
| Tests pass locally but recover on CI | Timing, network, service, data or environment differences | Inspect the CI failed-attempt artifact and first error; verify dependencies and make test setup deterministic. |
| Adding retries makes the suite much slower | Each retry repeats the whole test and per-test hooks | Reduce broad retry counts, scope overrides narrowly and fix the recurring failure. |
| Experimental strategy is rejected or ignored | The installed Cypress version or configuration does not support the selected option | Check the current docs and installed version; the documented strategies are experimental and available from 13.4.0. |
8. Performance, reliability and cost
Every additional test attempt costs another full execution plus its beforeEach and afterEach work. In a large suite, even a small retry allowance can add noticeable CI time if many tests fail intermittently. Keep the allowance small, scope exceptions narrowly, and use attempt history to prioritize fixes. A passing retry improves the chance of a green run, but it does not establish that the test is reliable.
For application screenshots used to inspect a visual failure, reproduce a stable URL and capture point; a screenshot cannot replace the Cypress error, assertion, or network evidence. ScreenshotNeo is a website screenshot API and MCP server from ScreenshotNeo. Its relevance here is capturing a page state for inspection, separate from Cypress retry behavior.
9. Or skip the browser setup
If you need a clean screenshot of a page involved in an intermittent failure, ScreenshotNeo takes a URL in one request. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
Cookie and consent banners, newsletter popups and chat widgets are removed before capture; each removal step can be turned off. Bot checks, blank pages and failed loads are never billed, and response headers identify page verdict and billing status. An MCP server gives AI agents screenshot, page-info and PDF tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month, with no card.
10. FAQ
Does a test that passes on retry count as flaky?
Yes. A recovered attempt can make the final result pass under standard retries, but the earlier failure still signals instability.
Does retries: 2 mean two total attempts?
No. It permits two additional attempts after the original, for up to three attempts total.
Do retries rerun every hook?
They rerun beforeEach and afterEach for the retried test. Failures in before and after hooks do not trigger a test retry.
Should I set retries to zero?
Zero is the documented default and gives immediate visibility into failures. A small CI allowance can be useful as a safety net, provided recovered failures remain visible to the team.
Is retry-ability the same as a test retry?
No. Retry-ability repeats linked queries and assertions while waiting; a test retry reruns the whole failed test.


