Happo Build Stuck Waiting for Screenshots? Common Fixes

If your Happo build is stuck waiting for screenshots, first find out which process is still active: your CI test command, Happo’s screenshot collection and submission step, or a Happo worker handling a submitted request. “Waiting for screenshots” is a symptom, not a diagnosis. Start with the exact CI step and the linked Happo run or report, then follow the branch that matches the evidence.

This guide covers the Playwright wrapper, other integration paths, blocked network requests, delayed assets, and when a single screenshot retry is appropriate. Happo’s integration packages and configuration can change, so check the current documentation and the versions installed in your project before copying older setup instructions.

1. Locate the step that is actually waiting

Open the CI job output and the Happo run or report link. Happo describes its general flow as code pushed, CI, screenshot capture, then baseline comparison. Note the last log line that appeared and whether the CI process is still running or has exited.

What you see	Likely area to inspect
The application test command never exits	Test runner, app server, open handles, or a test waiting for app readiness
The tests finish, but the Happo command does not finalize or print a report URL	Integration invocation, screenshot collection, submission, package versions, or network access from CI
A Happo run/report exists, but screenshots are pending or a worker request is slow	Happo run and worker logs; look for asset requests, blocked hosts, or errors
The report completed and only one image differs or looks wrong	That screenshot’s worker log and rendering inputs; this is a review/rendering issue, not an uncompleted build

Happo’s report logs bring snap-request logs into one searchable timeline. Search for the affected component or page, then expand the relevant snap-request log for context. [Read about Happo report logs](https://happo.io/blog/report-logs).

2. Check the integration command and installed packages

Playwright

For Happo’s documented Playwright integration, wrap Playwright with happo-e2e. This collects screenshots into one job; when the process exits, the command logs a URL to inspect. Check that the wrapper is present in the actual CI command, and that the test process exits normally.

npx happo-e2e -- npx playwright test

Compare the CI command with [Happo’s Playwright instructions](https://github.com/happo/happo-playwright). Older integration repositories are archived, and the Happo repository notes that integration packages were merged into happo. Don’t blindly add legacy packages because an old blog post or lockfile example names them; check Happo’s [current documentation](https://docs.happo.io/) and your installed versions.

Print the exact command and working directory used by CI.
Confirm the wrapper is invoked around the test command, rather than running tests alone and expecting a Happo job to finalize.
Check the output immediately before and after Playwright exits. If Playwright itself is still running, diagnose that process first.
Confirm the integration and CLI packages in the lockfile match the current setup guidance.
If the command exits but a run is incomplete, inspect the run and worker logs before changing timeouts.

Storybook, Cypress, and pages integrations

The precise collection command and configuration differ by integration. Confirm the command from the current guide for your integration rather than applying the Playwright wrapper to Storybook or Cypress. Check that CI starts the expected integration, that the app or Storybook is reachable at the configured address, and that any required build or server process stays available until capture completes.

For pages integrations, confirm the tested URL is reachable from the screenshot worker and, if hostname filtering is enabled, that the page’s hostname is allowed. For component integrations, identify the component or story that stops progressing and inspect its own data and asset dependencies.

3. Inspect blocked hosts and missing assets

Happo announced an allowedHostnames option on September 23, 2026. When configured, it controls which hosts snapshots may request; the option was off by default when announced. If it is enabled in your installed version, worker logs list allowed and blocked hostnames. A blocked API, font, image, or page host can make a capture incomplete or visually blank. [Read Happo’s announcement and examples](https://happo.io/blog/block-http-requests).

Open the worker log for an affected snap-request.
Look for blocked-host and failed-request entries near the screenshot capture.
Identify which resource the affected page actually needs: the tested page host, a font host, an image CDN, or an API.
Allow only the required hostnames in the relevant target configuration, following the syntax documented for your installed version.
Run the job again and confirm the resource loads and the resulting screenshot is complete.

For pages integrations, Happo explicitly notes that the tested page hostname must be allowed when the hostname control is active. If the page is blank, check this before changing screenshot timing. Do not assume hostname filtering caused the wait unless the option is active and the logs support that explanation.

4. Check page readiness, fonts, and asynchronous data

Happo says its documented Storybook and Cypress flows silence animations and wait for fonts and asynchronous assets. Those safeguards do not prove that every app-specific fetch, polling loop, websocket, or third-party request has completed before your screenshot. Inspect the actual worker log and application readiness behavior.

Make the screenshot state deterministic: use stable test data and wait for a meaningful app-specific ready condition where your integration supports it.
Check whether data requests return successfully in the worker environment; local browser access does not prove remote workers can reach the same service.
Verify fonts and images load from the worker. A font fallback or missing image may create a visual difference without causing a clear test failure.
Look for requests that never settle, repeated retries, timers, and app code that waits indefinitely for an external service.
Use the integration’s documented animation and asset handling instead of adding arbitrary sleeps as the first fix.

Happo’s guidance for Storybook and Cypress describes handling animations, asynchronous assets, and fonts in those workflows. Treat that as baseline behavior, not a guarantee that your application’s own data and network dependencies are ready. See the [Storybook integration guide](https://happo.io/blog/integrating-storybook-with-happo) and inspect the run logs for your specific capture.

5. Separate a stuck build from a single bad screenshot

If Happo has completed a report but one screenshot is a spurious diff, the single-screenshot retry feature can regenerate a specific screenshot from the report. It is a targeted remedy for an image in a completed report; it is not documented as a fix for a whole build that never completed. The feature’s older announcement lists minimum versions for happo.io, happo-plugin-storybook, and happo-static; verify current package instructions before upgrading or installing those legacy package names. [Read the retry announcement](https://happo.io/blog/introducing-single-screenshot-retry).

6. Troubleshooting by symptom

Symptom	Likely cause	What to do
Playwright ends but no Happo report URL appears	The documented wrapper may be missing, or the integration did not finalize	Use the documented `npx happo-e2e -- npx playwright test` invocation, check the exit status, and verify package versions.
CI remains active after tests appear done	A runner, server, timer, or open handle may still be alive	Find the active process and last output line. Check the test runner and server lifecycle before attributing the stall to screenshot workers.
A page capture is blank	The page host may be unreachable or blocked by active `allowedHostnames` filtering	Check worker logs and the configured hostname list; allow the tested page host if required.
Images or fonts are missing	A remote resource may fail, time out, or be blocked	Find the resource hostname in worker logs, confirm it is needed, then allow it if hostname filtering is enabled.
One or more components never become ready	An app-specific fetch or readiness condition may not resolve in the worker	Inspect the affected component’s network and readiness behavior; use deterministic test data and a real ready signal.
Report completes but one screenshot has a spurious diff	Rendering variation or an unstable external asset may affect that capture	Inspect the screenshot’s log and inputs. Consider single-screenshot retry only for the completed report case.
Logs do not explain the failure	The relevant CI output or worker context may be missing	Send Happo support the run link, failing CI step, integration type, installed package versions, and relevant logs. Happo directs users with unresolved issues to support.

7. Reliability, runtime, and cost considerations

A longer timeout can hide the symptom without fixing an unreachable host, a command that never exits, or an unresolved app dependency. First use the last CI output and worker logs to locate the wait. Avoid adding arbitrary delays to every capture: they add time to the suite and can still race with a slow dependency. Prefer predictable test data, explicit readiness, and the smallest necessary set of external hosts.

External resources make screenshots more dependent on services outside the build. Happo’s hostname announcement describes using the allow-list to control worker requests and points users to blocked-host details in logs. Introduce hostname restrictions carefully: blocking a needed font or image changes the render, so compare the resulting report and allow required hosts. The announcement includes one customer’s reduction from about 2,000 flaky examples to about 20; that is a single reported customer result, not a general guarantee or a rate of stuck builds.

For cost and run-time efficiency, narrow the failing branch before rerunning the full suite. Re-run the affected integration or capture when your workflow permits, and use single-screenshot retry only when a completed report contains one problematic screenshot. Check your Happo plan and current product guidance for account-specific billing details; this guide does not assume a price or billing outcome.

Or skip the browser setup

If you need a standalone screenshot for debugging a page or asset while tracking down a visual issue, [ScreenshotNeo](https://screenshotneo.com) takes a URL in one API request and returns an image or PDF. It is a separate website screenshot API, not a Happo integration or a way to complete a pending Happo run. See the [ScreenshotNeo API documentation](https://screenshotneo.com/docs/) for options.

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 and consent 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, and the Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.

Frequently asked questions

Does “waiting for screenshots” mean Happo is down?

No. The message alone does not identify the cause. Determine whether CI, the integration process, or a worker request is still active, then inspect the matching logs.

Should I retry the entire build or just one screenshot?

Use the failure stage to choose. A job that never completes needs CI and worker-log diagnosis. Single-screenshot retry is intended for one screenshot in a completed report.

Can ScreenshotNeo resolve a stuck Happo job?

No. It can capture a URL independently for debugging, but it does not submit or finalize Happo screenshots.