Percy Build Is Stuck Pending: Causes and Fixes
A Percy build stuck in receiving may be waiting for parallel shards or finalization. Use this checklist to identify the actual cause and fix it.
If a Percy build still shows receiving after tests finish, first check whether the run uses parallel shards and whether Percy received the expected shards or an explicit finalization command. “Pending” is often used informally for this symptom, but it does not identify one universal cause. Check the build’s exact status and error details before changing configuration.
This guide follows the official Percy troubleshooting distinctions: an unfinished parallel build, missing snapshots, a snapshot command that never ran, an upload problem, a rendering timeout, and a CI configuration error require different fixes. Start with the parallel-build branch below, then use the failure classification and logs to choose the next check. Percy’s parallel test suites guide and failure type reference describe these paths.
1. Confirm what is actually stuck
- Open the Percy build and record its exact status and any error banner. “Receiving” after test completion points first to incomplete parallel-build finalization; a failed banner or no-snapshots message points elsewhere.
- Confirm that the CI workflow and all test shard jobs have ended. A job still running, cancelled, or skipped may explain why the combined build has not completed.
- Check the Percy command output and CI logs for the last successful step: snapshot call, upload, and finalization are separate stages.
- Follow the branch matching the evidence. A longer rendering timeout cannot fix a missing shard, and changing shard totals cannot make a snapshot call that never ran.
2. Check parallel shards and finalization first
Percy groups parallel test work using a shared PERCY_PARALLEL_NONCE. The required completion step depends on how the total is configured.
| Configuration | How Percy knows the run is complete | What to verify |
|---|---|---|
Fixed PERCY_PARALLEL_TOTAL |
Percy waits for that number of finalized builds. | The configured total matches the shards that actually ran and finalized. |
--parallel or total -1 |
The run needs an explicit finalize-all operation. | Run npx percy build:finalize after all shards, with the same nonce. |
Fixed shard count
Compare PERCY_PARALLEL_TOTAL with the number of shard builds that actually completed and finalized. For example, if the total is four but only three shard builds completed, Percy can keep waiting for the fourth. Find the missing, failed, cancelled, or skipped job and either restore the intended shard or correct the configured total to match the run design.
Unknown shard count or explicit parallel mode
When the shard count is not known ahead of time, use parallel mode with total -1, then finalize after every test job has completed. The finalizer belongs in a downstream CI job that depends on all test shards:
npx percy build:finalizeSet the same nonce for every shard and the finalizer. The command reference documents build:finalize as the parallel-build finalization command: Percy CLI commands.
Nonce and CI configuration
- Use one shared
PERCY_PARALLEL_NONCEfor all shards belonging to a single CI run. - Use a different nonce for each distinct CI run. Reusing a value across reruns can collide with an already-finalized build.
- Make the finalizer depend on all shard jobs so it cannot run early. Check that cancellation or failure handling does not skip it unintentionally.
- If Percy does not automatically detect your CI provider, set the parallel variables explicitly on every relevant job.
- Ensure
PERCY_TOKENis available in each job that runs Percy, including the finalizer if required by your setup.
See the official build-not-finalized guidance and CI/CD environment configuration for provider-specific setup details.
3. If there are no snapshots, inspect test execution and credentials
A build with zero uploaded snapshots is not evidence by itself that finalization is the problem. Check whether tests reached the Percy SDK or CLI snapshot call and whether the test run failed before that point. Then verify the project’s PERCY_TOKEN is present in the CI worker environment and that the command ran successfully.
Use the build’s no-snapshots message and the job log to establish whether the command was skipped, failed, or could not authenticate. Percy’s failure reference distinguishes no snapshots from a build that was not finalized and from a snapshot call that was never made.
4. Match other errors to their own fix
| Build detail or symptom | Likely area to inspect | Next action |
|---|---|---|
| No snapshots uploaded | Test flow, snapshot command, token | Confirm the SDK or CLI call ran, tests reached it, and PERCY_TOKEN is set. |
| Build not finalized | Parallel job accounting | Check expected shard count or run the finalizer after every shard. |
| Snapshot command not called | Test runner integration | Verify the SDK is wired into the runner and the relevant test actually executed. |
| Snapshot upload failed | CI network egress or transient upload issue | Inspect upload logs and network access; retry when the evidence suggests a transient failure. |
| Rendering timed out or network idle failed | Page and resource reachability, rendering configuration | Check whether the page and required resources are reachable and inspect the documented rendering or network-idle settings. |
| CI pipeline error | Job environment | Check the token and parallel variables in the specific failing job, not only in another workflow step. |
Use the actual build classification and CI output to select a row; do not apply a timeout change to a shard-accounting problem. See Percy’s failure types for its classification.
5. Understand what waiting can and cannot do
percy build:wait waits for a build to finish and can gate later CI steps. The documented default timeout is ten minutes. Waiting does not close a parallel build that has an unaccounted shard or still needs explicit finalization. Fix shard accounting or run the required finalizer first, then use wait if a later step must depend on completed rendering. Command options are listed in the Percy command reference.
6. Troubleshooting checklist
- [ ] The dashboard status and error banner have been recorded exactly.
- [ ] All CI shard jobs have terminated, and the workflow did not skip a required job.
- [ ] The fixed total matches the shards that ran, or total
-1is paired with an explicit finalizer. - [ ] One nonce is shared within this run; a new nonce is used for a new run.
- [ ] The finalizer runs downstream of every shard.
- [ ]
PERCY_TOKENis present in the environment of the job that failed. - [ ] The snapshot command was reached, and uploads and rendering have their own log checks.
- [ ] A wait timeout is being treated as a wait limit, not as a substitute for finalization.
7. Performance, reliability, and cost notes
For this symptom, the useful reliability measure is whether every intended shard reports and whether finalization runs even when the CI workflow has failures or cancellations. Make the finalizer depend on all shards and inspect skipped-job behavior. Avoid increasing wait limits until the build’s actual stage is known; longer waiting only helps when work is still progressing.
Parallelization can reduce the time spent running test shards, but the configured total and finalization contract must match the workflow. The research documentation provides a four-shard example with three completed shards to explain why a fixed-count build can wait; it is an illustration, not a benchmark. The cited command reference’s ten-minute default for build:wait is a command default, not a guarantee that all builds render within that time.
Cost cannot be diagnosed from a “pending” label alone. Use the actual Percy account and build details for billing questions; the available troubleshooting documentation does not establish a price or imply that a subscription fixes shard or CI configuration.
Or skip the browser setup
If your next task is capturing a page for visual inspection or documentation, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. It is an alternative to try first when you need a direct screenshot call: consent banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed; and its MCP server lets AI agents use 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. See the API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.
FAQ
Why is my Percy build stuck in receiving?
One documented cause is incomplete parallel-build finalization, including a missing shard or missing finalizer. Check the build’s error details before assuming that is the cause.
Do all shards need the same nonce?
Yes. Shards and the finalizer for one run share a nonce; distinct CI runs need distinct values.
Does percy build:wait finalize the build?
No. It waits for completion. Parallel work still needs the correct shard accounting or explicit finalization.
What should I do if the build says no snapshots?
Verify that the test reached the snapshot call, that the command succeeded, and that the CI job has the project token.
