Cypress Timeout: How to Set, Increase and Fix Timeouts

What Is a Cypress Timeout?

A Cypress timeout is the maximum time Cypress spends retrying a command before it fails the test. Queries such as cy.get() and cy.contains() retry together with the assertions chained to them. Action commands such as .click() run once, after Cypress has waited for the element to become actionable within the same limit.

The Cypress retry-ability guide says each command that retries does so for up to 4 seconds, the defaultCommandTimeout setting. Before an action such as a click, Cypress also waits until the element is visible, enabled and not behind another element.

A timeout error names the command that ran out of time. That name is the first clue to whether the app was slow or the test waited for the wrong thing.

Cypress Default Timeout Values

The Cypress configuration reference lists five timeout options, all set in milliseconds. The defaults are 4000 for defaultCommandTimeout, 60000 for pageLoadTimeout, 5000 for requestTimeout, 30000 for responseTimeout and 60000 for taskTimeout.

Two settings sound related but never extend a wait. slowTestThreshold (10000 ms for E2E tests) only colors a slow test orange in the reporter, and retries reruns a failed test from the start.

execTimeout no longer belongs on the list: Cypress 16.0.0 removed it together with cy.exec(). The Cypress 16 section below covers the move to cy.task().

How to Set Timeouts in Cypress

Cypress reads timeouts from the command, the test or suite, Cypress.config(), the config file, the CLI and environment variables. Set the limit at the narrowest level that covers the slow step, so the rest of the suite keeps failing fast.

cy.get('#downloadButton').click()

// Retries for up to 15 seconds, then fails
cy.contains('.progress-label', 'Complete!', { timeout: 15000 })

// .should() has no timeout of its own: it inherits the query's
cy.get('.progress-label', { timeout: 15000 }).should('have.text', 'Complete!')

it('waits for the download', { defaultCommandTimeout: 15000 }, () => {
  cy.get('#downloadButton').click()
  cy.contains('.progress-label', 'Complete!')
})

describe('Download demo', { defaultCommandTimeout: 15000 }, () => {
  // every test in this block uses 15000 ms
})

// Runs when the spec file loads, so every test in the file gets 15000 ms
Cypress.config('defaultCommandTimeout', 15000)

describe('Download demo', () => {
  it('uses 15000 ms from the first test', () => {
    // ...
  })
})

CypressError: `Cypress.config()` cannot override `viewportWidth` during test execution
because it would affect the next test rather than the current one. Set `viewportWidth`
in the test configuration of a `describe`/`context` or `it` block instead. To change
the viewport during a test, use `cy.viewport()`.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  defaultCommandTimeout: 4000, // E2E and component tests
  e2e: {
    baseUrl: 'https://www.testmuai.com',
    defaultCommandTimeout: 15000, // E2E tests only
    pageLoadTimeout: 60000,
    requestTimeout: 5000,
    responseTimeout: 30000,
    taskTimeout: 60000,
  },
})

# One run, one value
npx cypress run --config defaultCommandTimeout=10000

# Environment variable (macOS and Linux shells)
export CYPRESS_DEFAULT_COMMAND_TIMEOUT=10000
npx cypress run

Reading a Cypress Timeout Error

Each timeout produces its own message, so the first line of the error tells you which setting ran out. These are the messages Cypress 16.2.1 prints for each case.

The rest of the error shows the failing command in the Command Log and the line of your spec that queued it. The Cypress debugging guide covers stepping through that log.

Cypress Timeout Demo on the Selenium Playground

The jQuery download progress bar demo on the TestMu AI Selenium Playground makes a good timeout target. After you click Start Download, the label reads Complete! about 8 to 10 seconds later, which is more than twice the default limit.

Default Timeout vs Per-Command Timeout

This spec runs the same download three ways: with the default, with a per-command timeout and with a per-test override.

describe('jQuery download progress bar', () => {
  beforeEach(() => {
    cy.visit('/selenium-playground/jquery-download-progress-bar-demo/')
    // jQuery UI turns #progressbar into a widget after the load event
    cy.get('#progressbar').should('have.class', 'ui-progressbar')
  })

  it('fails with the default 4000 ms timeout', () => {
    cy.get('#downloadButton').click()
    cy.contains('.progress-label', 'Complete!')
  })

  it('passes with a per-command timeout', () => {
    cy.get('#downloadButton').click()
    cy.contains('.progress-label', 'Complete!', { timeout: 15000 })
  })

  it('passes with a per-test override', { defaultCommandTimeout: 15000 }, () => {
    cy.get('#downloadButton').click()
    cy.contains('.progress-label', 'Complete!')
  })
})

• Default 4000 ms - fails with "Timed out retrying after 4000ms: Expected to find content: 'Complete!' within the selector: '.progress-label' but never did."
• Per-command timeout of 15000 ms - passes, with each test finishing in 8 to 10 seconds including the page visit.
• Per-test defaultCommandTimeout of 15000 ms - passes in 8 to 12 seconds, leaving headroom under the 15-second limit.

The screenshot Cypress saved at the failure shows the download dialog less than a third done when the 4000 ms limit ran out. The app was working, and the test gave up before the download could finish.

Clicking Before the Page Is Ready

The beforeEach hook above waits for #progressbar to get the ui-progressbar class before clicking. The page loads jQuery UI after its load event, and jQuery UI attaches the button's click handler, while cy.visit() resolves at the load event itself.

Drop that line and the click reaches the button before the handler exists:

it('times out even with a 15 s timeout', () => {
  cy.visit('/selenium-playground/jquery-download-progress-bar-demo/')
  cy.get('#downloadButton').click()
  cy.contains('.progress-label', 'Complete!', { timeout: 15000 })
})

This test fails with "Timed out retrying after 15000ms" even though the limit is almost twice the download time. The download dialog never opened, so the label never changes however long Cypress waits.

The fix is a readiness check, here the ui-progressbar class, before the click. Use the same pattern on any page that attaches handlers after load, such as a single-page app that hydrates on the client.

Covered Click on the Cloud Grid

On the TestMu AI cloud grid, with Windows 11 and Chrome 156, both overrides passed in every session. In two of three sessions, though, the first test failed at the click rather than at the assertion:

CypressError: Timed out retrying after 4050ms: `cy.click()` failed because this element:

`<button class="... ui-button ui-corner-all ui-widget" id="downloadButton">Start D...</button>`

is being covered by another element:

`<img role="img" src="https://assets.testmuai.com/resources/images/logos/logo.svg" alt="TestMu AI Logo" ...>`

Fix this problem, or use {force: true} to disable error checking.

Cypress scrolls an element into view before acting on it, and at that moment the site header sat over the button. The click's actionability check retried until defaultCommandTimeout ran out, which shows that the same setting governs clicks as well as queries.

Setting scrollBehavior: 'center' on the suite did not prevent it, and later tests in the same session clicked normally. A covered-element error points at page state, such as a header, a banner or a layout shift over the target, so find what covers the element before changing any timeout.

Note: Run the same Cypress specs on TestMu AI's cloud browsers, with the Cypress and Node.js versions pinned in lambdatest-config.json, and compare each session's logs with your local run. To try it, start free.

Network Timeouts in cy.wait() and cy.request()

According to the Cypress cy.wait() docs, waiting on an alias happens in two periods. Cypress first waits up to requestTimeout, 5000 ms by default, for a matching request to leave the browser, then up to responseTimeout, 30000 ms by default, for the server to respond.

The spec below triggers each failure on purpose. The second test delays a request the Playground page sends during load, so no click is involved.

describe('Network wait timeouts', () => {
  it('requestTimeout: no matching request is sent', () => {
    cy.intercept('GET', '**/api/orders*').as('getOrders')
    cy.visit('/selenium-playground/dynamic-data-loading-demo/')
    cy.wait('@getOrders', { requestTimeout: 2000 })
  })

  it('responseTimeout: cy.wait() sees the request but not the response', () => {
    cy.intercept('GET', '**/api/country-details', (req) => {
      req.on('response', (res) => res.setDelay(8000))
    }).as('getCountry')
    cy.visit('/selenium-playground/dynamic-data-loading-demo/')
    cy.wait('@getCountry', { responseTimeout: 3000 })
  })

  it('responseTimeout: cy.request() to a slow endpoint', () => {
    cy.request({ url: 'https://httpbin.org/delay/5', timeout: 2000 })
  })
})

• No matching request - "cy.wait() timed out waiting 2000ms for the 1st request to the route: getOrders. No request ever occurred."
• Slow response to a matched request - "cy.wait() timed out waiting 3000ms for the 1st response to the route: getCountry. No response ever occurred."
• Slow cy.request() - "cy.request() timed out waiting 2000ms for a response from your server." The error also prints the method and URL Cypress sent.

A "1st request" error usually means the intercept's method or URL pattern does not match what the app sends, so raising requestTimeout rarely helps. A "1st response" error points at the backend. The Cypress intercept guide covers route matching in detail.

Timeout Changes in Cypress 16

Cypress 16.0.0 removed the cy.exec() command and the execTimeout option, both deprecated in 15.21.0, according to the Cypress changelog. Calling cy.exec() now throws, and setting execTimeout prints a warning and is otherwise ignored.

CypressError: `cy.exec()` was removed in Cypress version 16.0.0. Please update to use
`cy.task()` instead, which runs in Node and does not depend on the operating system,
shell, or terminal of the machine running Cypress.

Move the shell command into a task in setupNodeEvents, then give the call its own timeout in the spec.

// cypress.config.js
const { defineConfig } = require('cypress')
const { execSync } = require('child_process')

module.exports = defineConfig({
  e2e: {
    taskTimeout: 60000,
    setupNodeEvents(on) {
      on('task', {
        seedDatabase() {
          execSync('node scripts/seed.js', { stdio: 'inherit' })
          return null
        },
      })
    },
  },
})

// In the spec, replacing cy.exec('node scripts/seed.js')
cy.task('seedDatabase', null, { timeout: 120000 })

The same release changed other behavior that touches waits and timeouts:

• Node.js 22, 24 or 26+ - Cypress 16 dropped Node.js 20, so CI images and cloud runners need a supported Node version before any timeout setting matters.
• Cookie and storage reads retry - cy.getCookie(), cy.getCookies(), cy.getAllCookies(), cy.getAllLocalStorage() and cy.getAllSessionStorage() are now queries that retry their assertions until they pass or reach defaultCommandTimeout.
• Runtime config limits - viewportWidth, viewportHeight and blockHosts can no longer be set with Cypress.config() during a test; set them in test configuration or call cy.viewport().
• Visibility checks - under the default modern visibility strategy, should('be.visible') passes as soon as the element is rendered, so it no longer waits out an element covering it. Action commands such as .click() still refuse a covered element.

Timeouts on a Cloud Grid

A cloud grid adds limits around the whole session, on top of the Cypress timeouts inside each test. On TestMu AI, the Cypress run settings include max_duration, which stops a test session after 2 to 240 minutes so one stuck spec cannot hold a parallel slot.

{
  "run_settings": {
    "build_name": "Cypress Timeout Demo",
    "parallels": 2,
    "specs": "./cypress/e2e/download-timeout.cy.js",
    "useNodeVersion": "22",
    "npm_dependencies": { "cypress": "16.2.1" },
    "max_duration": 30
  }
}

Cypress 16 runs on Node.js 22, 24 or 26 and later, so pin useNodeVersion to 22 next to the Cypress version. TestMu AI reads the Cypress version from npm_dependencies before package.json.

On HyperExecute, globalTimeout caps a task at 1 to 150 minutes, with 90 as the default, and retryOptions retries a scenario only when its logs match a regular expression. The HyperExecute YAML reference lists Cypress among the frameworks those regex retries support.

globalTimeout: 90
retryOnFailure: true
maxRetries: 2
retryOptions:
  errorRegexps: ["for your remote page to load"]

That pattern retries page-load timeouts, which often come from network or infrastructure delays, and leaves assertion timeouts failing. A retried assertion timeout that passes on the second attempt hides a wait problem you still need to fix.

TestMu AI's automation cloud runs Cypress specs across 3,000+ browser and OS combinations in parallel and records command logs, video, network logs and console logs for every session. Those artifacts explain a timeout that only happens in CI, like the covered button in the demo above.

Cypress Timeout Best Practices

• Read the error before changing a number - the first line names the command and the setting. Fix a wrong selector, an early click or a covered element before you touch a timeout.
• Scope the override - set the timeout on the slow command first, then the test, and globally only when the whole app is slow. The Cypress retry-ability guide gives the same advice and recommends against changing the command timeout globally.
• Wait for readiness, not for time - assert on a signal that the page is ready, like the ui-progressbar class, instead of a fixed cy.wait(5000). The cy.wait() docs call arbitrary waits an anti-pattern.
• Use timeout: 0 for instant checks - a check that something must not exist right now should run once rather than retry for 4 seconds.
• Keep CI values out of the code - set a slower CI limit with CYPRESS_DEFAULT_COMMAND_TIMEOUT or --config, so local runs keep the faster default.
• Retry only infrastructure errors - limit grid retries to page-load or network errors, so a flaky wait still fails where you can see it.

For more habits that cut flaky waits, see Cypress tips and tricks. The Cypress should command guide covers how assertions retry, and exception handling in Cypress covers failures that are not timeouts.

Teams that run several frameworks hit the same problem with different settings: Playwright timeouts and Selenium waits cover the equivalents. To check your Cypress fundamentals, take the Cypress 101 certification.

Conclusion

Take the first line of your failing test's error, match it to the error table above, and fix the cause before you raise a limit; when you do raise one, set it on the slow command. If a timeout fails only in CI, run the spec on TestMu AI's cloud browsers using getting started with Cypress testing, then compare the session's command log and video with your local run.

Testing from the terminal? Kane CLI by TestMu AI lets SDETs and developers plan, write, run and debug tests from the command line.

To run your first test, start free, or

book a demo

for a full walkthrough of the product.