Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
The reliable fix is to identify which half of cy.wait('@alias') timed out. Cypress first waits (by default, 5,000 ms) for a matching request to leave the browser, then waits (by default, 30,000 ms) for its response. A request-phase timeout usually means the intercept was registered too late, the method or URL matcher is wrong, or the browser served the response from cache. A response-phase timeout means the request matched but the server, proxy, or intercept handler did not finish.
Register the route before cy.visit() or the click that triggers fetch, match the real request precisely, inspect the Command Log, and only then increase a bounded wait timeout for a genuinely slow service.
Start with the timeout phase
Read the error text before changing configuration. Cypress uses two separate waits for an aliased intercept:
| Phase | Default | What it means | Most likely causes |
|---|---|---|---|
| Request | 5,000 ms (requestTimeout) |
No matching request left the browser in time. | Late registration, wrong method, URL/path/query mismatch, or a cache hit. |
| Response | 30,000 ms (responseTimeout) |
A matching request was observed but no response completed. | Slow or failing upstream service, a hanging handler, authentication or proxy problems, or Cypress-version behavior. |
Increasing a timeout cannot make an unmatched route match. First prove that the request exists and that your route describes it.
Register the intercept before the fetch
The route must exist before the browser sends the request. Put it before cy.visit() when the page fetches during startup, or before the click/submit command that starts the request.
describe('users', () => {
it('waits for the users fetch', () => {
cy.intercept('GET', '**/api/users*').as('getUsers')
cy.visit('/users')
cy.wait('@getUsers').then(({ request, response }) => {
expect(request.method).to.equal('GET')
expect(response.statusCode).to.equal(200)
})
})
})If the intercept is placed after cy.visit(), a startup fetch may already have happened and cy.wait() will wait for a request that will never be observed.
Register before user actions too
cy.intercept('POST', '**/api/orders').as('createOrder')
cy.get('[data-cy=submit-order]').click()
cy.wait('@createOrder').its('response.statusCode').should('eq', 201)Match the request Cypress actually sends
cy.intercept() can match an exact URL, glob, regular expression, or fields such as method, hostname, pathname, query, and headers. Use the browser’s Network panel and the Cypress Command Log to copy the actual method and URL rather than guessing from application code.
Method matters
// This will not match a POST:
cy.intercept('GET', '**/api/users').as('users')
// Match the request's real method:
cy.intercept('POST', '**/api/users').as('users')Host, path, and query parameters
A relative-looking application call can become a fully qualified URL after a base URL, proxy, or environment variable is applied. Query strings also vary between runs. A glob is often safer than an exact string:
cy.intercept({
method: 'GET',
hostname: 'api.example.test',
pathname: '/v1/users',
query: { page: '1' }
}).as('getUsers')When the query is not relevant to the assertion, use **/v1/users* so the matcher accepts the query string. When it is relevant, match it explicitly and assert the resulting request object.
Inspect what was captured
cy.wait('@getUsers').then((interception) => {
cy.log(interception.request.url)
cy.log(interception.request.method)
expect(interception.response).to.exist
})The Command Log should show the route under Routes and a matching badge on the request. If no badge appears, focus on registration, method, URL, and cache—not response timeout values.
Handle legitimate slow responses without hiding failures
When the route is definitely matching and the service has a documented longer budget, override the wait locally:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
cy.wait('@getUsers', { timeout: 60000 })cy.wait() also accepts requestTimeout and responseTimeout overrides. Keep the number tied to a known service budget. A global increase makes unrelated failures slower and can conceal a broken endpoint.
cy.wait('@getUsers', {
requestTimeout: 10000,
responseTimeout: 60000
})Prefer a deterministic stub for tests that are not intended to measure the real service:
cy.intercept('GET', '**/api/users*', {
statusCode: 200,
body: { users: [{ id: 1, name: 'Ada' }] }
}).as('getUsers')Cypress 16 response-handler behavior
Cypress 16 changed the native network path: the browser now makes the upstream request. The migration guidance states that responseTimeout does not apply to response handlers and recommends bounding the test with an explicit cy.wait('@alias', { timeout: 10000 }). Cypress still gives up when no response arrives within a fixed 30-second limit for that condition.
If your intercept callback returns a Promise, Cypress waits for that Promise before continuing the request. Keep callback work finite. Call req.continue() to reach the real server, or req.reply() to provide a stubbed response.
Recommended Free Tools
cy.intercept('GET', '**/api/report', (req) => {
req.continue((res) => {
// Keep asynchronous work bounded and finite.
res.send()
})
}).as('report')
cy.visit('/reports')
cy.wait('@report', { timeout: 10000 })For a fully stubbed route, reply immediately:
cy.intercept('GET', '**/api/report', (req) => {
req.reply({ statusCode: 200, body: { ready: true } })
}).as('report')When fetch appears invisible: browser cache
cy.intercept() observes network traffic, not a response satisfied entirely from the browser cache. A cached fetch may therefore render successfully while never triggering your alias.
- Open browser developer tools and check whether the request says it came from memory or disk cache.
- Inspect response headers from the development server and disable caching for the resources under test.
- As a test-only workaround, add a top-level intercept that removes cache headers for the relevant resources, then verify that the request is genuinely sent.
Do not “fix” a cache problem by merely increasing cy.wait(); no new network request will appear.
Separate page interception from API health with cy.request()
Use cy.request() to test the endpoint independently of browser JavaScript, service workers, and intercept matching. It has its own response timeout and accepts a per-request timeout.
cy.request({
method: 'GET',
url: `${Cypress.env('apiBaseUrl')}/api/users`,
timeout: 60000,
failOnStatusCode: false
}).then((response) => {
expect(response.status).to.be.oneOf([200, 401, 403])
})A 401 or 403 points to credentials or environment setup; a redirect or unexpected host points to URL configuration; a timeout here indicates service or network latency rather than a Cypress alias problem. If cy.request() succeeds quickly but cy.wait() does not, revisit route timing, matching, cache, and the page's actual request.
A repeatable diagnosis checklist
- Read whether the failure is waiting for a request or for a response.
- Move
cy.intercept()and.as()beforecy.visit()or the triggering action. - Copy the method, hostname, pathname, and query from the Network panel.
- Confirm the route and matching badge in the Cypress Command Log.
- Check for a browser-cache or service-worker response.
- Inspect the yielded interception's URL, status, and body.
- Run the endpoint with
cy.request()to isolate server behavior. - Choose a local timeout override only after the above checks, and keep it within the service's agreed budget.
- For deterministic tests, stub with
req.reply(); for integration coverage, usereq.continue()and keep handlers finite.
Common errors and precise fixes
“No request ever occurred”
The route was probably registered after the request, or the matcher is wrong. Move registration earlier, verify the HTTP method, and broaden or correct the URL matcher.
The route appears, but no response arrives
Check server logs, authentication, proxy rules, redirects, and the endpoint directly with cy.request(). Then inspect any intercept callback for a Promise that never settles or a missing req.continue()/req.reply().
The page works, but the alias times out
Look for a browser-cache or service-worker hit. Disable caching in the test environment or arrange for the request to reach the network.
A longer timeout makes the suite painfully slow
Undo the global change and set a bounded timeout only on the known slow alias. If the endpoint exceeds that budget, fix or stub the dependency instead of masking the regression.
Free tools Windows power users keep installed
One-click scans. No signup required.
Or skip the browser setup
If your goal is to capture a rendered page or test artifact rather than debug Cypress interception itself, ScreenshotNeo provides a one-request screenshot API. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and each response identifies the page verdict and billing status.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for parameters and response details. The service also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots each month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
FAQ
Can I set only responseTimeout to solve every alias timeout?
No. A request-phase timeout is governed by request discovery and matching. A response override helps only after Cypress has observed the matching request.
Does a successful fetch() prove that cy.intercept() should have matched?
No. The browser may have served the response from cache, or the request may differ from the route in method, host, path, or query.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchShould end-to-end tests always stub the API?
No. Stub when deterministic data is the goal; allow the real service when integration behavior is the subject, while keeping a documented response budget and independent health checks.
Frequently Asked Questions
What is the fastest first check when cy.wait times out?
Determine whether Cypress was waiting for a request or for its response; the two phases have different causes.
Why does changing the global timeout often make debugging worse?
It slows every unrelated failure and cannot correct a route that never matches.
What should an intercept callback do to let the real request continue?
Call req.continue(), and ensure any returned Promise settles in a finite amount of time.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
