Common Issues
Element Selection Problems
Element Selection Problems
Issue: Elements not found or interactions failingSolutions:
- Use browser dev tools to test selectors
- Add explicit waits for dynamic content
- Use more specific or stable selectors
- Check for iframe or shadow DOM elements
Timing and Race Conditions
Timing and Race Conditions
Issue: Tests failing due to timing issuesSolutions:
- Use
waitForSelector()instead of fixed delays - Wait for network requests to complete
- Wait for the element you need with a web-first assertion instead of
waitForLoadState(), which can time out on pages with slow third-party scripts. See Intermittent failures - Implement proper error handling and retries
Authentication and Session Issues
Authentication and Session Issues
Issue: Login failures or session timeoutsSolutions:
- Verify credentials are correct and active
- Handle multi-factor authentication scenarios
- Use session storage for authentication state
- Test login flow separately from main workflow
Performance and Timeout Issues
Performance and Timeout Issues
Issue: Tests timing out or running too slowlySolutions:
- Optimize page load performance
- Increase timeout values for slow operations
- Use parallel execution where possible
- Monitor and alert on performance degradation
Missing traces or videos
Missing traces or videos
Issue: A result has no trace or video, or some pages have no videoSolutions:
- Check whether the run failed. Scheduled runs keep the trace and video only when the check fails. Runs from the editor keep them whether the check passes or fails, and so do runs you record with
npx checkly test --recordornpx checkly trigger --record. See Viewing trace files. - Don’t rely on the
traceandvideooptions in your Playwright configuration. Browser checks ignore them, so you can’t keep artifacts for passing scheduled runs or turn off video recording. To control them, use a Playwright Check Suite and setuse.traceanduse.video. - Open pages from the test’s own
pageorcontextfixture. Playwright records one video per page in that context. Pages from a context you create withbrowser.newContext()have no video. See Playwright’s videos guide. - Set a test timeout below the 240-second run limit, for example
test.setTimeout(210000). A test that times out on its own test timeout keeps its trace and video. A test still running when the check reaches the run limit is stopped without them. See Browser check timeouts.
Error Handling and Debugging
Wait Strategies
Wait Strategies
Error Recovery
Error Recovery
Intermittent failures
A check that passes most of the time and sometimes fails usually has a timing problem in the script: it acts before the page is ready, waits for something that doesn’t always happen, or matches an element the user can’t see. Checkly runs each Browser check with one worker, no Playwright retries and Playwright’s default test timeout of 30 seconds, unless you set your own withtest.setTimeout(). Each run starts a new browser.
Start from a failed result. Read the error and its call log, then open the trace and video to see what the page showed when the step failed. Scheduled runs keep the trace and video only when the check fails. See Viewing trace files.
Hard waits
Hard waits
Issue: The check fails with an unexpected value, or with When the wait is longer than the time left, the test times out during the wait.Solutions:See Waits and timeouts.
page.waitForTimeout: Test timeout of 30000ms exceeded.A fixed wait with page.waitForTimeout() is either too short or too long. When the page is slower than the wait, the next step reads the page too early:- Remove
page.waitForTimeout()calls. - Use web-first assertions and locator actions. They wait until the element is ready, up to their timeout:
The load event or network idle never happens
The load event or network idle never happens
Issue:
page.goto: Test timeout of 30000ms exceeded. with waiting until "load" in the call log, or page.waitForLoadState: Test timeout of 30000ms exceeded.page.goto() waits for the page’s load event by default. The load event waits for every script and image on the page, including third-party tags such as analytics and marketing pixels. If one of them hangs, load doesn’t fire, even when your page has already rendered. waitForLoadState('networkidle') waits until there have been no network requests for 500 ms, so a page that polls an API or keeps a request open never reaches it. Third-party scripts can be slow from one location and fast from another, which makes the failure look random.In the trace, the network tab lists the request that never finished.Solutions:- Don’t wait for
networkidle. Playwright discourages it. - Navigate with
waitUntil: 'domcontentloaded', then wait for the element you need:
- If a third-party script isn’t part of what you monitor, you can block it with
page.route(). Your check then won’t notice when that script breaks your page. See Avoid network interception in synthetic monitoring.
Redirects that race with the next step
Redirects that race with the next step
Issue:
page.goto: net::ERR_ABORTED, or the step after a click fails because the page changedSome pages redirect a moment after they load, for example to a login or consent page. When the script clicks or navigates just before the redirect, the redirect cancels that navigation. Whether the script wins the race depends on timing, so the check fails only sometimes.Solutions:- Wait for the final URL before the next step:
page.waitForURL('**/final') works too.browserType.launch: Target page, context or browser has been closed
browserType.launch: Target page, context or browser has been closed
Issue: The run fails with
browserType.launch: Target page, context or browser has been closedThe browser stopped while it was starting, before your test code ran. The result has no video.Solutions:- Check whether the next runs passed. If the check uses retries, a failed run is retried: Checkly runs the whole check again with a new browser.
- If the error keeps coming back, contact support@checklyhq.com with a link to the failed result.
Failures that started after a runtime change
Failures that started after a runtime change
Issue: The check fails more often since its runtime changed, for example after a new account default runtimeEach runtime comes with its own Playwright and Chromium versions, so a runtime change can change timing and behavior.Solutions:
- Run the check on the previous runtime and compare the results. With the CLI, set
runtimeIdon the check, for exampleruntimeId: '2025.04', and runnpx checkly test --verbose. The run log names the runtime it used, for exampleCreating runtime version 2025.04. To do this in the web app, see Overriding runtimes for specific checks. - If the check passes on the previous runtime and fails on the new one, compare the traces of both runs to find the step that behaves differently.
Failures from one location only
Failures from one location only
Issue: The check fails from one location and passes from othersA third-party script, CDN or network path can be slow from one region only. Compare failed and passing results from different locations, and look at the network tab in the trace for slow requests. See Managing false positives for retries and multi-location setups that reduce alerts for regional problems.