To debug a Percy snapshot locally, rerun the same test command through Percy’s CLI and choose the mode that fits the failure: use --debug to inspect asset discovery without creating a build or uploading snapshots, or --verbose when you need full CLI logs and want Percy to receive the snapshots. Neither flag opens an interactive debugger. Then classify the failure—test invocation, asset discovery, page readiness, upload, rendering, or parallel finalization—and inspect the corresponding local or hosted logs.
1. Reproduce the same test command through Percy
Start with the command that runs the relevant test or snapshot workflow in your project. Wrap it in percy exec, preserving the command and its arguments after --. For example:
npx percy exec --debug -- npm testReplace npm test with the project’s actual test command. This runs Percy SDK functions such as DOM capture and asset discovery, but Percy says the --debug mode does not create a build or upload snapshots. It is useful when the question is whether assets are being discovered, not when you need to inspect a newly uploaded snapshot in Percy. See Percy CLI debugging documentation.
Run the command in the same project directory and environment as the failing workflow where possible. A different test selection, missing environment variable, or different browser/app configuration can make a local reproduction misleading.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors#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.
2. Choose the right Percy logging mode
| Mode | What it does | Use it when |
|---|---|---|
--debug |
Provides asset-discovery diagnostics and suppresses build creation and snapshot uploads. | You want to investigate which assets Percy discovers without producing a Percy build. |
--verbose |
Logs more of the CLI’s activity while still creating a build and uploading snapshots. | You need a Percy build and its hosted evidence, or need fuller CLI logs for the actual upload path. |
These modes answer different questions; --debug is not a more detailed version of an interactive debugger, and it will not give you a new hosted build to inspect. Percy’s CLI option set can change, so if a flag is rejected, check the help and version for the CLI installed in your project.
3. Classify the failure before changing settings
Use the narrowest matching failure category in Percy’s guide rather than changing timeouts, hosts, or test settings at random. Percy distinguishes build-level failures—such as no snapshots, an unfinalized build, resource upload problems, or rendering timeouts—from snapshot-level failures such as an SDK call that never ran, a page-load failure, or a snapshot upload error. The official guide’s categories and steps are at Snapshots Missing or Failed.
| What you observe | First checks | Evidence-led next step |
|---|---|---|
| No snapshots uploaded | Did the selected test run? Did it reach a Percy snapshot call? Was the test integrated with Percy’s SDK/CLI path? Is PERCY_TOKEN available? |
Run the intended command through Percy and inspect the classified build failure. |
| Snapshot command was not called | Check test selection, integration wiring, and whether the test actually invokes the SDK or percy snapshot. |
Fix the test or integration path before tuning capture settings. |
| Resources are missing | Identify failed or slow asset requests; check host access, authentication, and lazy-loaded content. | Use Percy Network logs to establish which request failed before adjusting allowed hosts or capture timing. |
| Page-load or network-idle timeout | Look for pending requests and determine whether the page or target element was ready at capture time. | Set a specific wait or change the relevant timeout only when the observed request pattern supports it. |
| Snapshot upload failed | Check whether the snapshot URL is valid and whether the runner has stable outbound network access. | A retry can help identify a transient issue; investigate persistent egress or connectivity failures. |
| Parallel build was not finalized | Check whether the final pipeline stage ran after all shards completed. | Run percy build:finalize after the parallel work is complete. |
4. Check invocation, token, and parallel-run setup
Confirm the snapshot path actually ran
A Percy build cannot contain snapshots if the selected test did not execute a Percy snapshot call. Confirm that the failing test was included in the run and that the integration invokes the relevant Percy SDK or CLI command. A green test run by itself does not prove that the test submitted a snapshot.
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.
Verify the token without exposing it
Percy’s failure guide says each Percy run requires PERCY_TOKEN. Check that it is present in the local process or CI job that runs Percy, but do not print or paste the secret into shared logs. A missing or unavailable token is an environment/setup problem; changing snapshot waits will not address it. See Percy’s build-failure guidance.
Recommended Free Tools
Verify parallel finalization
For parallel builds, check the applicable parallel configuration, including PERCY_PARALLEL_NONCE and PERCY_PARALLEL_TOTAL, and confirm that a finalization step runs after all shards finish. If finalization runs too early or never runs, the build can remain incomplete even if individual test jobs executed.
5. Investigate missing assets and capture timing
When the page appears but styles, fonts, images, or other resources are absent, identify the actual requests and statuses instead of assuming the screenshot renderer failed. Percy’s hosted Network logs can show request URLs, failures, and timing. Check whether the runner can reach the asset host, whether the resource needs authentication, whether the request failed or remained pending, and whether the asset is lazy-loaded after the snapshot was taken.
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.
Also check when capture occurs. If the application has not finished rendering or the target element is not present, configure an explicit readiness condition rather than applying a broad delay by default. For CLI-configured snapshots, Percy documents waitForSelector and waitForTimeout; use them when the logs point to a readiness issue. See Percy’s wait options.
The CLI reference also documents asset-discovery options such as --allowed-hostname and --network-idle-timeout, as well as --disable-cache and --dry-run (which prints snapshot names without taking snapshots). These are targeted controls, not general fixes. Check the installed CLI’s help/version before relying on an option, and change one setting at a time so the result remains interpretable. The options are listed in the Percy CLI reference.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →6. Inspect the Percy-hosted build when local logs are not enough
A local run and Percy’s hosted build expose different stages. If the failing run created a build, open the Percy project’s Builds tab, select the build, and click Debug on the failed-build banner or snapshot card. The Smart Debug panel provides:
- Overview: the failure classification and relevant log line.
- Network logs: request-level evidence for missing, failing, or slow resources.
- Troubleshoot: guided steps connected to the detected failure.
For a hang or timeout that has no useful ERROR or WARN line, inspect the full log view. Percy’s Smart Debug documentation says logs are retained for one month, and that downloading build logs requires Percy CLI 1.28.4 or later; these product details may change. Consult the current Smart Debug documentation for availability and steps.
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
7. Separate upload errors from rendering and timeout problems
If capture appears to have occurred but upload fails, investigate whether the runner can reach Percy reliably and whether the snapshot URL is valid. A retry is useful only as a diagnostic for a potentially transient network failure; repeated failures call for checking network egress and the error details rather than blindly retrying.
For page-load or network-idle failures, inspect what is still pending and how the application settles. A request that never completes, a persistent connection, or content that appears only after a user action can affect when capture is considered ready. Increase a timeout only after identifying the relevant wait condition; the right value depends on the application and its request pattern.
Or skip the browser setup
If your goal is to capture a URL rather than debug Percy’s integration, ScreenshotNeo offers a one-request screenshot API. Its cookie-consent handling accepts banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status. It also offers an MCP server with screenshot, page-info, and PDF tools for AI agents. Plans include 1,000 screenshots per month free with no card and paid options starting at $5 for 3,000; every feature is on every plan. See ScreenshotNeo.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpFor API parameters and other supported options, see the ScreenshotNeo API documentation. Sign up for 1,000 free screenshots a month with no credit card.
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.
Frequently Asked Questions
Does Percy’s --debug flag open a debugger?
No. It adds asset-discovery diagnostics and prevents build creation and snapshot uploads; it is not an interactive debugger.
Can a local --debug run show Percy’s hosted rendering result?
No. Because that mode does not create a build or upload snapshots, use --verbose when you need a build and its hosted logs.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
