Percy Cannot Find a Page or URL: Common Fixes

When Percy cannot find or load a page URL, first confirm that the snapshot URL is correct, uses http or https, and is reachable from Percy’s rendering environment. Configure authentication if the page is protected. Then identify whether the failure is page loading, asset capture, or snapshot upload: those are separate stages with different fixes.

Start with the failed build’s classification and Network logs before changing settings. Percy documents failure types, snapshot upload troubleshooting, and Network logs.

1. Identify which stage failed

Symptom	Likely stage	First checks
Percy reports a page load timeout	Page loading or reachability	Validate the URL, test access from Percy’s rendering environment, and configure required authentication.
The snapshot URL is rejected or upload fails	URL format or snapshot upload	Use an absolute `http` or `https` URL and inspect runner network stability.
The page appears, but its visual content is incomplete	Asset discovery or loading	Inspect image, CSS, JavaScript, font, and other asset requests; check host access and authentication.
Network requests fail and the source is unclear	Diagnostics	Read the failure classification and Network logs for the failing URL and request status.

A page that loads successfully can still have missing assets. Likewise, a captured snapshot that cannot upload does not prove that the page URL is missing. Treat the stage as a diagnostic clue, not as interchangeable error wording.

2. Validate the snapshot URL

Copy the exact URL Percy is meant to open and check its hostname, path, port, and scheme.
Use an absolute URL beginning with http:// or https://. Percy’s upload troubleshooting documentation gives about:blank as an invalid URL example.
Open the URL in a browser and confirm it resolves to the intended page rather than a redirect, login wall, error page, or empty route.
Check for environment-specific hostnames, expired preview links, malformed escaping, and missing path segments.

For a URL sourced from a file or generated by a test, inspect the final resolved value, not just the template or relative path. Percy CLI can take targets from a snapshot file, a static directory, or a sitemap URL; a snapshot-file entry must resolve to a URL a browser can navigate to. See the Percy CLI guide.

3. Check that Percy can reach the page

A URL loading on a developer’s laptop does not establish that Percy’s renderer can reach it. Private network addresses, local development servers, VPN-only hosts, firewall rules, IP allowlists, and short-lived preview environments can make a page unavailable to the renderer.

Check whether the target host is publicly reachable or otherwise exposed to Percy’s rendering environment.
Review firewall, proxy, VPN, and IP-allowlist rules for blocked access.
Verify that DNS resolves to the intended host and that the required port accepts connections.
Check redirects and TLS configuration. Confirm that each redirect destination is also reachable.
For an ephemeral preview, make sure it is running and the URL has not expired when the snapshot job starts.

If the build classifies the issue as Page Load Timeout, Percy’s documented first checks are URL reachability from Percy and authentication where required. Avoid increasing timeouts until you have ruled out an unreachable or incorrect target.

4. Configure authentication for protected pages

If a route requires a login, Percy must receive the authentication setup needed to reach the actual page. Without it, the renderer may load a login screen, receive an authorization error, or fail to reach the route. Check the snapshot’s resulting page and request logs to distinguish these outcomes.

Confirm whether the page requires a session, credentials, or access to a protected API.
Use your project’s supported Percy authentication setup and ensure it is available to the rendering job.
Check that credentials or session state have not expired and that the account can access the exact route.
If page HTML is public but assets are protected, authenticate those asset requests too.

Do not place secrets in a URL or commit credentials in a snapshot file. Follow your CI system’s secret-handling practices and confirm the authentication configuration is applied to the job that runs Percy.

5. If the page loads, inspect its assets

When the page shell renders but images, styles, scripts, or fonts are absent, troubleshoot the asset requests independently of the document URL.

Open the Percy build’s Network logs and identify failed requests by URL and status.
Check whether each asset hostname is correct and reachable from the renderer.
Verify authentication for protected asset endpoints and confirm any required hostnames are allowed in the Percy configuration.
Check whether the asset URL is generated dynamically, expires, or depends on a browser session.
Review network-idle behavior if assets load late. Percy’s documented configuration includes allowed hostnames and a network-idle timeout.

Network logs include request statuses plus URL, timestamp, and device-configuration context. These details can help distinguish a bad asset URL from a broader access or infrastructure problem. See how to view Percy Network logs.

6. If capture succeeded but upload failed

An upload failure occurs after snapshot capture and should be handled as an upload or network-path problem. BrowserStack recommends checking network stability and retrying; if the issue persists, inspect the runner’s network path. The failure guide also helps distinguish upload trouble from a page-load failure.

Confirm the build actually reports an upload failure rather than a page-load timeout.
Check whether the runner lost network access or encountered a transient connection problem.
Retry when appropriate and inspect whether failures recur consistently or only intermittently.
If retries continue to fail, inspect proxy, firewall, and network rules on the runner between it and Percy.

A retry can help with a temporary network interruption, but it will not correct an invalid URL, blocked page, or missing authentication.

7. A diagnostic sequence for a failed build

Read the build classification. Note whether Percy reports page loading, upload, or another failure category.
Inspect the exact snapshot URL. Confirm the absolute URL, scheme, host, route, and port.
Check renderer reachability. Look for private-host access, firewall, DNS, redirect, or preview availability issues.
Verify authentication. Confirm protected routes and their assets are accessible to the snapshot job.
Inspect Network logs. Find the failed request and use its URL, status, timestamp, and device context to locate the layer at fault.
Change one relevant setting at a time. For example, correct a hostname, authentication setup, allowed hostname, or network-idle timeout, then review the next build’s diagnostics.
Reclassify if needed. If the page loads but assets are absent, follow the asset path; if the snapshot exists but upload fails, follow the runner network path.

8. Common errors and fixes

Problem	Likely cause	Fix
URL is invalid or rejected	Relative, malformed, unsupported, or non-browser URL such as `about:blank`	Pass an absolute, navigable `http` or `https` URL.
Page Load Timeout	Wrong URL, renderer cannot reach the host, or required authentication is missing	Validate the URL, verify renderer reachability, and configure access for protected routes.
Page works locally but not in Percy	Local, private, VPN-only, allowlisted, or unavailable preview host	Expose the environment to Percy’s renderer and check network controls and preview lifetime.
Page appears without images or styles	Asset host is blocked, URL is wrong, endpoint is protected, or assets load too late	Use Network logs; check asset URLs, host allowlisting, authentication, and network-idle settings.
Snapshot captured but upload fails	Network instability or runner path issue	Check runner connectivity, retry a transient failure, and inspect proxy or firewall rules if it persists.
Snapshot file points to the wrong page	Base URL or path resolution produced an unexpected target	Inspect the final URL entry and confirm it is browser-navigable.

Or skip the browser setup

If the goal is to inspect or capture a page outside Percy’s visual-test workflow, ScreenshotNeo provides a website screenshot API and MCP server. Its API accepts a URL and returns an image or PDF; see the ScreenshotNeo site and API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import 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}`);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. 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; paid plans start at $5 for 3,000 screenshots.

Performance, reliability, and cost notes

Performance: A slow page, late assets, or a network-idle condition that never settles can delay capture. First confirm the page and assets are reachable; tune the relevant wait behavior only after diagnosing the cause.
Reliability: A stable, reachable preview URL and valid authentication reduce environment-specific failures. Use build classifications and request logs to locate intermittent network problems.
Cost: The cited Percy troubleshooting pages do not establish a per-failure charge, so this guide makes no billing claim about Percy. For ScreenshotNeo, only clean shots are billed; responses include X-Page-Verdict and X-Billed headers, and cache hits cost nothing. Check those response headers when accounting for API results.

FAQ

Does a Percy page-load timeout mean the URL is nonexistent?

No. It means Percy could not load the snapshot page. The URL may be wrong, unreachable from Percy, or protected by authentication that is not configured.

Can Percy accept a page that works only on my laptop?

Not unless the rendering environment can reach it. A local or private address needs an access path available to Percy.

Where do I look when only images or styles are missing?

Inspect the build’s Network logs and focus on the failed asset requests, their hostnames, and any authentication requirements.

Is a snapshot upload failure the same as a missing page?

No. Upload troubleshooting concerns a captured snapshot’s network path to Percy; page-load troubleshooting concerns opening the target URL.