Start by identifying which stage is timing out: Percy page loading, network-idle asset discovery, or capture readiness. Those failures have different fixes. Check the exact error and Percy network logs before increasing a timeout; then verify access, wait for the UI state you need, address slow or never-settling requests, and tune only the setting tied to the diagnosed bottleneck.
Identify which Percy timeout you have
Percy describes a page timeout as the page remaining in a loading state for more than 30 seconds during asset discovery. That documented threshold describes Percy’s page-timeout guidance; it is not a guarantee that every SDK or version will behave identically. See Percy’s page-timeout troubleshooting guide.
Do not treat every timeout as a slow page load. Percy distinguishes page-load failures from network-idle failures, and a snapshot taken before an element appears is a separate readiness problem. The relevant error label and network evidence point to the right branch.
- Page-load timeout or page loading failed: Percy could not load the page. Check reachability and authentication first.
- Network-idle timeout: The page did not reach the expected quiet period during discovery. Look for requests that remain pending or keep recurring.
- Blank/loading capture or missing late content: The page may load, but the snapshot may happen before the UI reaches the state you want. Use a readiness condition such as a stable selector.
Work through the failure in order
- Read the exact failure label. Note whether the build reports a page-load timeout, network-idle timeout, blank/loading capture, or a snapshot missing an element that appears later. Percy’s troubleshooting guide describes failure types and their checks.
- Confirm Percy can access the URL. Open the same target in the capture environment where possible, and check whether the page requires a cookie, basic authorization, or another authentication step. Configure the required access rather than attempting to solve an access problem with a longer timeout.
- Inspect Percy’s network logs. Look for failed or unusually slow requests. Percy’s page-timeout guidance specifically notes SVG and video assets as possible slow-loading content. For network-idle failures, check third-party trackers, analytics, and requests that stay pending or continually restart.
- Wait for the application state you need. If navigation succeeds but content is rendered asynchronously, wait for a stable completion element with
waitForSelector. UsewaitForTimeoutonly when a fixed delay is the practical readiness signal and its duration is understood. Percy documents these snapshot controls in the CLI snapshot documentation and JavaScript core package documentation. - Check lazy-loaded content. If the page loads images or sections only when scrolled into view, trigger that loading before snapshot capture. Percy’s troubleshooting guidance suggests scrolling to the bottom for pages using lazy loading.
- Change only the setting that matches the evidence. For page-load failures, consider Percy’s documented page-load timeout setting and available CI resources. For network-idle failures, inspect pending requests and consider the relevant network-idle timeout. Configuration details are in the Percy CLI configuration reference.
- Re-run with debug output and classify again. The Percy CLI supports debug mode for asset discovery. After each change, compare the new failure label and network evidence with the original so you can tell whether you fixed the failing stage.
Fix page-load timeouts
When the page remains in the loading state during asset discovery, first identify which request is holding things up. A slow SVG or video, a failed asset, or limited CI capacity may be more relevant than the timeout value alone. Percy suggests increasing PERCY_PAGE_LOAD_TIMEOUT; its guide gives 60000 as an example value in milliseconds:
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
PERCY_PAGE_LOAD_TIMEOUT=60000
This is a documented troubleshooting suggestion, not a universal setting or assurance of success. Confirm the environment-variable syntax and behavior for the Percy CLI and SDK version installed in your project. If the logs show a specific asset is not necessary for the snapshot and can safely be omitted from the captured DOM, Percy’s domTransformation is another possible remedy. Do not remove content that is needed for the visual test.
Consider CI resource limits as well. If the capture environment is constrained, evaluate whether more resources or lower test concurrency would help; that trades CI capacity or execution time against the chance of completing discovery. Make that change when the evidence points to resource pressure, not as a substitute for fixing inaccessible pages or a request that never settles.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Fix network-idle timeouts
A network-idle failure means Percy did not observe the expected period with zero network requests within discovery’s timeout. Use the logs to find requests that never finish, recur continuously, or are held open by trackers, analytics, or other third-party services. The configuration reference defines network-idle-timeout in relation to the duration with zero network requests.
If the application is otherwise ready and a known request prevents quiescence, consider extending the network-idle timeout using the setting supported by your installed Percy version. If a tracker or asset is unnecessary to the visual test, address that request or consider an appropriate capture-specific exclusion. Increasing the page-load timeout alone does not directly address requests that prevent network idle.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Fix captures that are early, blank, or stuck loading
Wait for a stable element
When the page loads but the target UI appears later, use waitForSelector for an element that signals the state the test needs—for example, a results panel after a search completes. Prefer a meaningful UI signal over an arbitrary pause because it ties capture timing to the page’s state.
Use a fixed delay only when necessary
waitForTimeout can help when no reliable selector or other readiness signal exists. Choose a delay based on the application’s known behavior, and understand that a fixed sleep can still be too short when the page is slower than usual or waste time when it is faster.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Check JavaScript and lazy loading
Percy’s troubleshooting guidance says that if a page is blank or stuck loading while enable-javascript: true, try enable-javascript: false. Verify the option’s correct syntax for your SDK and confirm the application is ready before requesting the snapshot. For lazy-loaded content, scroll it into view or otherwise ensure it has loaded before capture.
Choose a fix based on the evidence
| Evidence | Likely problem | Next action | Scope and trade-off |
|---|---|---|---|
| Page-load timeout; a request is slow or fails | Navigation or asset discovery is not completing | Verify access, inspect the request, then consider PERCY_PAGE_LOAD_TIMEOUT or CI resources |
A timeout or resource change can affect more than one page; fix a page-specific asset where appropriate |
| Network-idle timeout; requests remain pending or recur | The page does not reach zero network requests for the expected period | Inspect persistent requests and consider the network-idle setting | Target the requests preventing quiescence; do not change unrelated page-load settings |
| Capture misses content that appears later | Snapshot readiness happens before the relevant UI state | Wait for a stable selector; use a measured fixed delay only if needed | A semantic selector is tied to application state; a fixed sleep is simpler but less adaptive |
| Blank or loading capture with JavaScript enabled | The page may be stuck in the configured rendering behavior | Check application readiness and try disabling JavaScript where Percy’s guidance applies | Verify SDK-specific syntax and ensure disabling JavaScript will not remove content the test requires |
Or skip the browser setup
If your goal is simply to produce a website screenshot rather than diagnose Percy specifically, ScreenshotNeo is a screenshot API and MCP server for developers. One GET request captures a URL:
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
See the ScreenshotNeo API documentation for request options. Cookie banners are accepted and removed before the shot, along with supported newsletter popups and chat widgets; those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up free for ScreenshotNeo.
Troubleshoot common cases
- The timeout persists after raising
PERCY_PAGE_LOAD_TIMEOUT: Recheck whether the error is actually network idle or an access failure. Raising the page-load timeout will not make an unreachable page accessible or stop recurring requests. - The page is protected: Configure the required cookie or basic authorization for Percy’s capture environment, then rerun the same URL.
- An image-heavy page still fails: Use the network log to identify the slow asset rather than assuming all images are the cause. Percy calls out SVG and video as possible slow assets.
- The snapshot is blank or stuck loading: Verify the application has reached its ready state; if
enable-javascript: trueis in use, try the documented alternative of disabling it, with syntax checked against your SDK. - Content is missing but the build does not time out: This is likely a readiness issue. Wait for the content’s stable selector or ensure lazy-loaded content has been brought into view.
- A timeout option appears ineffective: Confirm the installed Percy CLI/SDK version and that the setting is configured in the correct environment and syntax for that version.
Keep captures reliable without hiding real failures
- Prefer a stable selector over a long fixed sleep when the application exposes a meaningful ready state.
- Use page-specific exclusions or DOM transformation only for assets that are genuinely unnecessary to the visual assertion.
- Change one cause-aligned setting at a time, then rerun the failing case and inspect the new label and logs.
- If CI is resource-constrained, weigh adding resources or reducing concurrency against its cost and runtime effects.
Frequently Asked Questions
Does Percy’s 30-second threshold mean every timeout is exactly 30 seconds?
No. Percy’s page-timeout guide describes a page remaining in the loading state for more than 30 seconds during asset discovery; installed versions and other failure types may differ.
What should I use instead of a fixed wait?
Use a stable UI selector with Percy’s `waitForSelector` when the page exposes a reliable completion signal.
Quick 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.
