Happo Screenshots Are Missing: How to Troubleshoot CI Builds

When Happo screenshots are missing from a CI build, first find which stage did not complete: CI preparation, snap-request submission, worker rendering, or loading the page and its assets. A CI check or report landing page alone does not prove that screenshot requests were sent. Start with the CI job output, then use the report’s searchable snap-request logs to investigate errors, missing assets, or work that finished too late.

1. Confirm CI reached the screenshot stage

Happo’s flow can announce a run before the CI job has finished setup. The job may still need to build Storybook, upload assets, or complete other preparation before screenshot requests arrive. Check the job output around those steps and confirm that the integration actually submitted snap requests. A report existing without snapshots can mean the run began but request submission did not happen.

1. Find the first Happo-related command or integration step in the CI log.
2. Check whether the Storybook build or other test page preparation completed successfully.
3. Check for the asset upload step if your integration uses one.
4. Look for output showing that screenshot requests were submitted. If there is no such evidence, troubleshoot the CI command, integration, and configuration before investigating worker rendering.

Happo describes a CI run followed by screenshot capture and comparison; setup can continue after the run has been announced. See its engineering posts about the CI and capture flow for that distinction.

2. Check configuration, secrets, and working directory

If the requests do not appear to have been submitted, confirm the CI job is using the intended Happo configuration and credentials. Happo’s repository example passes apiKey and apiSecret in happo.config.ts, sourcing them from HAPPO_API_KEY and HAPPO_API_SECRET. The documented CLI is npx happo; it discovers configuration files from the project root.

// happo.config.ts — use the configuration shape documented for your integration
export default {
  apiKey: process.env.HAPPO_API_KEY,
  apiSecret: process.env.HAPPO_API_SECRET,
};

This is an illustrative minimal configuration shape, not a complete configuration for every Happo integration. Check the current repository documentation for your package and integration before copying it. In CI, verify that both environment variables are present without printing their values. Also verify that the command runs from the expected project root and that the intended config file is discoverable.

• Check the secret names in the CI provider and the names read by the config.
• Check that secrets are available for this event type; some CI systems restrict secrets for external contributions.
• Check that the job uses the expected package, integration, and version.
• Do not echo or otherwise expose API key or secret values in build logs.

Happo documents its configuration and CLI in its official repository. Exact settings vary by repository and integration.

3. Find the failed or missing snap request in report logs

Once requests have been submitted, open the report’s logs page. Happo combines logs from the report’s snap requests into a searchable timeline. Search for the component or target name, scan highlighted warnings and errors, then expand the full log for the affected request. The logs can reveal explicit request errors as well as quieter problems such as an image returning 404, a font taking too long, or asynchronous work finishing after the screenshot was captured.

1. Open the report and follow its logs link. Happo says the logs page is linked from comparison, report, and async-report views.
2. Search for the component or snap-request name that is missing.
3. Expand its full worker log and note the first relevant error or warning, not only the final failure line.
4. Compare a missing request with a successful request from the same report. Differences in timing, URL, target, or asset loading can narrow the cause.

When a request errors, its logs are the most direct evidence. If the report has no relevant snap request at all, return to CI setup and submission rather than assuming the worker failed.

4. Check asset access and allowed hostnames

A worker may render a page while being unable to fetch its images, fonts, stylesheets, or other external resources. That can produce incomplete screenshots or fallback fonts. Check the worker log for allowed and blocked hostnames, and confirm that every required asset host is reachable under the target’s configuration.

Happo announced a target-level allowedHostnames option on September 23, 2026. At the time of that announcement it was off by default, and Happo said it planned to block external requests by default in a future major version. The pages integration also needs the hostnames of the pages being tested to be allowed; otherwise the worker can capture an empty page. These behaviors are version- and configuration-sensitive, so inspect the installed package version and target settings before changing them.

• If images disappear, inspect their hostnames and HTTP responses in the worker logs.
• If text uses a fallback font, check font host access and whether the font finished loading before capture.
• If a pages integration captures a blank page, verify that the page’s own hostname is allowed.
• If you enable hostname restrictions, include the page and asset hosts that the capture requires, following the package version’s documentation.

See Happo’s announcement on blocking HTTP requests and confirm the option’s current behavior against your installed version.

5. Separate a one-off bad snapshot from a recurring failure

For one isolated faulty screenshot, Happo’s Single Screenshot Retry can regenerate a snapshot from the report’s source page rather than rerunning the full suite. The announcement lists minimum versions for happo.io, happo-plugin-storybook, and happo-static, updated September 17, 2025. Check the current package documentation for prerequisites before relying on this feature.

A retry can help recover an individual spurious result, but it does not identify or fix a repeatable problem. If the same component repeatedly fails, use its worker logs to address the underlying asset, timing, network, or request issue.

6. Troubleshooting by symptom

Symptom	Likely stage	What to check
A CI check or report exists, but there are no snapshots	Preparation or submission	Did Storybook build and assets upload? Did the integration submit snap requests? Check the CI output around the Happo command.
No report or no Happo activity appears	CI invocation or configuration	Confirm the command ran, the working directory is the project root, the config is discoverable, and the job has the expected secrets.
Only one component or target is missing	Specific snap request or target	Search the report logs for that request; compare its full worker log and target configuration with a successful request.
The screenshot exists but images are missing	Asset loading or network policy	Look for 404 responses or blocked hostnames; verify the image host is reachable and allowed.
Fonts or layout differ intermittently	Asset timing or asynchronous work	Check font-load warnings and whether asynchronous rendering completed before capture. Fix the page readiness condition where your integration supports it.
The pages integration captures an empty page	Page host blocked or page unavailable	Check the tested page’s hostname against the target’s allowed hostnames and inspect worker logs for blocked requests.
A single snapshot is a one-off failure	Transient request or worker issue	Check logs, then use Single Screenshot Retry if your package versions meet its prerequisites. Investigate repeat failures at their source.

7. Escalate with a useful evidence bundle

If the report and CI logs do not explain the failure, contact Happo technical support at support@happo.io. Include the report link, affected component or snap request, CI job output around setup and submission, and relevant worker-log lines. This context makes it possible to distinguish a request that never arrived from a worker or page-loading failure. Remove credentials and other secrets before sharing logs.

Performance, reliability, and cost considerations

Missing screenshots are often a pipeline visibility problem: the run can begin while setup is still underway, so confirm that capture requests were submitted before attributing delay to rendering. Slow or late assets can also affect what the worker captures. Use request logs to distinguish queue or rendering delay from page readiness and network failures. Happo has published internal queueing figures, but those describe its service operations and are not a prediction of an individual build’s duration.

Retries are useful for an isolated bad snapshot, while repeated retries can conceal a recurring issue. The dossier does not establish Happo pricing or a general cost model, so check the current vendor plan details for account-specific cost questions.

Or skip the browser setup

If the task is to capture a page rather than troubleshoot Happo’s visual regression run, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for parameters and response details.

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 accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up free for 1,000 screenshots a month, with no card required.

Frequently asked questions

Does a Happo report mean screenshots were captured?

No. A run can be announced before setup finishes and before snap requests arrive. Verify submission in the CI output and confirm requests appear in the report logs.

Where can I find logs for one missing snapshot?

Open the report’s logs page and search for the component or snap request. Expand the matching entry to inspect its complete worker log.

Should I rerun the entire CI suite?

First determine whether requests were submitted and whether the failure is isolated. Happo’s Single Screenshot Retry may suit one faulty snapshot when the installed packages meet its prerequisites; recurring failures need log-based diagnosis.

What should I send Happo support?

Send the report link, affected request or component, CI output around Happo setup and submission, and relevant worker-log lines. Remove secrets from the logs before sharing.