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 problemsStart by rerunning the same test command through Percy, then choose the mode that matches the question: --debug for asset discovery without creating a build or uploading snapshots, or --verbose when you need full CLI logs and want the run to reach Percy. A local run can narrow down the cause, but some rendering and network evidence is available only in Percy’s hosted build debug view.
Reproduce the failure with the same test command
Use the command and test selection that produced the failed snapshot. The package manager and test-runner command vary by project; the important part is to run it through Percy’s CLI and pass the test command after --.
As an Amazon Associate I earn from qualifying purchases.
npx percy exec --debug -- <your test command>For example, replace <your test command> with the command your project already uses to run the relevant tests. Percy documents this mode as running SDK work such as DOM capture and asset discovery without creating a Percy build or uploading snapshots. It is useful for questions about which page assets Percy discovers, not as an interactive debugger. Percy’s SDK debugging documentation
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Choose the right Percy logging mode
| Mode | What it does | Use it when |
|---|---|---|
--debug |
Provides verbose asset-discovery information; does not create a build or upload snapshots. | You want to inspect discovery without sending snapshots to Percy. |
--verbose |
Logs CLI activity while still allowing a build to be created and snapshots uploaded. | You need detailed CLI output and hosted build evidence. |
These modes are not interchangeable: use the first to isolate discovery, and the second when the upload/build path is part of the diagnosis. Percy’s CLI reference also documents --dry-run for printing snapshot names without taking snapshots. Check the help output and version of the CLI installed in your project if an option is unavailable or its behavior differs. Percy CLI reference
#1 Best Overall
Classify the failure before changing configuration
Percy distinguishes build-level failures from snapshot-level failures. A build can fail because snapshots were not uploaded, finalization did not happen, a resource upload failed, or rendering timed out. At snapshot level, the SDK call might never have run, page loading might have failed, or an upload might have failed. Match the observed failure to Percy’s Snapshots Missing or Failed guide before changing waits, host rules, or timeouts.
| Observed failure | Check first | Evidence-led next step |
|---|---|---|
| No snapshots uploaded | Did the test execute a Percy snapshot call through the SDK/CLI integration? Is PERCY_TOKEN available to the run? |
Repair test selection or SDK/CLI wiring, then rerun through Percy. |
| Snapshot call was not made | Did the test actually run, and does the selected test invoke Percy? | Check integration setup and test selection. |
| Resources are missing | Which asset URLs failed, and are their hosts reachable and authorized? Is the content lazy-loaded? | Use Network logs to identify failed requests before adjusting host access, authentication, or capture timing. |
| Page-load or network-idle timeout | Which requests remain pending? Was the page or target element ready at capture time? | Set an appropriate wait or adjust the relevant timeout based on the observed request pattern. |
| Snapshot upload failure | Is the snapshot URL valid, and can the runner maintain network egress? | A retry can help identify a transient issue; investigate persistent connectivity failures. |
| Parallel build was not finalized | Did the final pipeline stage run after all shards completed? | Ensure percy build:finalize runs after all shards. |
Check invocation, token, and parallel-run setup
Confirm the snapshot path ran
A successful test command does not by itself prove that Percy received a snapshot. Verify that the selected test called the Percy SDK or the project’s percy snapshot path and that the run actually used the Percy integration.
Rank #2
Confirm the token is available
Percy requires PERCY_TOKEN for every Percy run. Check that it is present in the process environment without printing or sharing its value; do not paste secrets into shared logs. If local execution works but CI does not, compare how the environment variable is provided in each environment.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Check parallel builds and finalization
For a parallel run, verify that the parallel settings expected by that build are configured, including PERCY_PARALLEL_NONCE and PERCY_PARALLEL_TOTAL where applicable. The build must also be finalized after all shards finish; otherwise a build may remain incomplete even when individual test jobs ran.
Inspect asset requests and capture readiness
When CSS, fonts, images, or other resources are missing, inspect the request URLs, status codes, and timing rather than immediately adding a broad wait. A request can fail because the host is inaccessible or requires authentication; an image or other asset may also not have loaded because it is lazy-loaded or capture happened too early.
For CLI-configured snapshots, Percy documents waitForSelector and waitForTimeout. Use them when logs indicate that a specific element or delay is needed before capture. Percy’s troubleshooting guidance also covers asset-discovery options such as --allowed-hostname, --network-idle-timeout, and --disable-cache; consult the installed CLI help and the relevant docs before changing them. CLI options · Failure-specific troubleshooting
Rank #4
- Used Book in Good Condition
Use Percy’s hosted debug view when local output is not enough
- Open your Percy project and select Builds.
- Open the failed build.
- Click Debug on the failed-build banner or on the relevant snapshot card.
- Use Overview to review the failure classification and relevant log line.
- Use Network logs to investigate missing, failing, or slow requests; use Troubleshoot for guided steps associated with the detected failure.
If the run hangs or the failure is not shown on an ERROR/WARN line, inspect the full-log view. Percy’s current Smart Debug documentation says logs are retained for one month and that downloading build logs requires Percy CLI 1.28.4 or later; these are product behaviors that may change. Percy Smart Debug documentation
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Separate upload problems from rendering timeouts
A snapshot that was captured but failed to upload points toward a different problem than a page that never became ready. For upload failures, confirm the snapshot URL and whether the runner can make stable network connections to the required services. For page-load or network-idle timeouts, inspect pending requests and the page’s settling behavior first. Increase a timeout only when the request pattern indicates more time is genuinely needed; the appropriate value depends on the application and its network activity.
Best Value
Or skip the browser setup
If your goal is to capture a site rather than diagnose a Percy integration, ScreenshotNeo is a website screenshot API and MCP server for developers. It accepts one GET request for a URL and returns an image or PDF; its optional cleanup removes cookie/consent banners, newsletter popups, and chat widgets before capture.
For example, cURL can save a WebP screenshot from a single request:
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 API documentation for request options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
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 matchFrequently Asked Questions
Does Percy’s --debug flag open a debugger?
No. It adds asset-discovery diagnostics and suppresses build creation and snapshot uploads; it is not an interactive debugger.
Should I always use --debug instead of --verbose?
No. Use --debug for non-uploading asset-discovery checks, and --verbose when you need detailed CLI logs while creating a build and uploading snapshots.
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.
