AI agents are now live in Website Scanner! Enter your URL and fix website issues 3x faster with AI. Explore now!
No Result Found
Connect and get help from 7,000+ developers on our Discord community. Ask the CommunityAsk the Community

Build failure types and resolution guides

Reference list of the most common Percy build failure classifications, what each one means, and how to resolve it.

When a Percy build fails, the UI assigns it a classification. Each classification maps to a resolution guide with a description, recommended steps, a documentation link, and (where relevant) a suggested config snippet. This page covers the most common classifications, grouped by where the failure typically originates.

Need a refresher on how to open the debug view? See Smart debug for Percy builds.

Most common failures

Most teams hit one of the following failures. If you are skimming, jump to these rows first:

  • No Snapshots Uploaded: Your test suite ran but Percy never received any snapshots. Usually a missing or wrong PERCY_TOKEN, or the SDK was never wired in.
  • Build Not Finalized: You are running parallel builds but percy build:finalize was never called after the last shard.
  • Snapshot Command Not Called: A specific test ran but did not call percy snapshot (or the SDK equivalent).

Look these up in the tables below for the full fix path.

How classification works

Percy looks at two signals to classify a failure:

  • Build-level failure reason: Set by the Percy backend when a build is finalized in a failed state (for example, no snapshots were ever uploaded).
  • CLI error buckets: Patterns matched against Percy CLI logs for the build (for example, the snapshot command exited with a port-in-use error).

The Overview tab shows the most specific match it can find. The tables below cover both layers.

Build-level failures

These failures appear as the headline classification on the failed build banner.

Classification (UI label) What it means Typical fix Docs link
No Snapshots Uploaded (no_snapshots) The build was started and finalized but Percy never received any snapshots. Confirm percy snapshot or your SDK call ran successfully in CI. Check that PERCY_TOKEN is set on the CI worker. Snapshot command reference
Resource Upload Failed (missing_resources) Snapshots were uploaded but Percy could not fetch the assets needed to render them. Confirm assets are reachable from Percy’s renderers. Set discovery.allowedHostnames for any private hosts. Asset discovery
Build Not Finalized (missing_finalize) A parallel build was started but percy build:finalize was never called. Run percy build:finalize after all parallel test machines have completed. Parallel test suites
Rendering Timed Out (render_timeout) Percy’s renderers did not complete the build within the time budget. Reduce snapshot count per build, or set discovery.networkIdleTimeout to give pages more time to settle. Render configuration
Build Manually Failed (manually_failed_build) Someone (or your CI) explicitly failed the build through API or UI. Review who failed it and why. Both are shown on the banner. Issues with snapshot comparisons

CLI and environment failures

These failures come from the Percy CLI’s own logs and are detected automatically.

Classification (UI label) What it means Typical fix Suggested config
Percy Port Already in Use (port_already_in_use) The CLI could not bind to its default port (5338). Stop the conflicting process, or run Percy on a different port with the --port flag. percy exec --port 5339 -- <command>
Browser Launch Failure (browser_launch_failure) Chromium failed to start in the CI environment. Install required system libraries. On Linux runners this often means libnss3, libatk1.0-0, and similar. N/A
Browser Permissions Issue (permissions_issue) The browser could not launch because of system permissions. On Windows, add an antivirus exception for the Percy browser binary. On Apple Silicon, install Rosetta (softwareupdate --install-rosetta). N/A
Browser Spawn Failure (browser_spawn_failure) The browser binary could not be spawned because of permissions or a missing dependency. On Windows, add an antivirus exception for the Percy browser binary. On Apple Silicon, install Rosetta. Confirm the binary has execute permissions. N/A
Network Binding Issue (network_binding_issue) The CLI could not bind to the local server because IPv6 is unavailable. Enable IPv6 on the runner, or force the server to bind to localhost. PERCY_SERVER_HOST=localhost:5338
Network Idle Timeout (network_idle_failed) A snapshot’s page never reached network idle within the discovery timeout. Mark third-party trackers or analytics as discoverable, or extend the network idle timeout. PERCY_NETWORK_IDLE_WAIT_TIMEOUT=750

Snapshot capture failures

These failures are detected per snapshot and shown in the Overview tab when you debug a failed snapshot.

Classification (UI label) What it means Typical fix
Snapshot Command Not Called (snapshot_command_not_called) The build ran but no percy snapshot (or SDK equivalent) call was made for this test. Verify your SDK is wired into the test runner and the test actually executed.
Page Load Timeout (page_load_failed) Percy could not load the page being snapshotted. Confirm the URL is reachable from Percy and authentication (if any) is configured.
Snapshot Upload Failure (upload_snapshot_failure) The snapshot was captured but failed to upload to Percy. Retry the build. Persistent failures usually indicate a network egress issue from the CI runner.
Parallel Build Not Finalized (finalize_command_not_called_for_parallel_build) A parallel build started but percy build:finalize was never called. Detected at the snapshot level. Add percy build:finalize as a final pipeline step.
CI Pipeline Error (probable_user_ci_error) Heuristic match for a CI configuration error (environment variables, runner misconfig, and similar). Check PERCY_TOKEN, PERCY_PARALLEL_NONCE, and PERCY_PARALLEL_TOTAL in the failed build’s environment block.

Asset capture failures

These failures usually point at the asset-discovery layer. Asset capture failures happen when Percy cannot fetch the resources required to render a snapshot accurately, which can lead to incomplete snapshots and false positives in your visual diffs. The affected resources typically include:

  • Images and icons
  • Stylesheets (CSS files)
  • JavaScript files
  • Fonts
  • Media files (videos, audio)
  • Third-party resources (CDN assets, external APIs)
Classification (UI label) What it means Typical fix
Asset Loading Failed (asset_load_missing) A required asset returned 404 during discovery. Confirm the asset URL is correct and reachable from Percy’s renderers.
Asset Server Errors (asset_load_5xx) A required asset returned a server error during discovery. Investigate the host serving that asset. Retry the build once it is healthy.
Assets Not Uploaded (asset_not_uploaded) An asset failed to upload to Percy from the CLI. Retry the build. Persistent failures indicate CI egress restrictions.
Asset Collection Failed (snapshot_assets_collection_failed) Percy could not collect one or more assets because they were inaccessible, too large, or blocked by CORS. Confirm assets are reachable and within size limits, and resolve any CORS restrictions. Enabling gzip compression can help with large assets (PERCY_GZIP=true).

Prevent asset capture failures

Follow these practices to minimize asset failures in future builds:

  • Configure allowed hostnames: Proactively add all external domains that host assets for your application using the discovery.allowedHostnames config.
  • Set appropriate timeouts: Configure discovery.networkIdleTimeout based on your application’s typical load times.
  • Configure authentication: Set up credentials for any protected asset endpoints.
  • Validate asset URLs: Make sure all asset URLs are absolute and use the correct protocol (http or https).
  • Monitor build logs: Review the Overview and Network logs tabs to catch issues early.
  • Test locally: Use the --debug flag when running Percy locally to troubleshoot asset discovery without consuming screenshots.

Run Percy locally with the --debug flag:

Run Percy locally with debug output
Copy icon Copy

For more information, see Asset discovery and Debugging SDKs.

Suggested config snippets

Each resolution guide may include a config suggestion you can paste directly into your project. Suggestions live in one of two places, depending on the setting.

In .percy.yml

For settings that affect Percy’s renderers and asset discovery:

Example: .percy.yml configuration
Copy icon Copy

See Percy CLI configuration for the full schema.

In your CI environment

For settings that affect the CLI process or your test runner:

Example: CI environment variables
Copy icon Copy

PERCY_TOKEN is required on every Percy run. PERCY_PARALLEL_NONCE and PERCY_PARALLEL_TOTAL are required only for parallel test suites. Set them on every shard.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked





Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked





Thank you for your valuable feedback!

Talk to an Expert
Download Copy Check Circle