How to Fix Reg-suit Missing Reference Image Errors

A Reg-suit missing reference image does not identify one cause by itself. First check whether a baseline exists for the selected snapshot key. On an initial run, no reference may be expected: the official Puppeteer demo reports images as new, publishes them, and uses those published snapshots as expected images on the next run. If this is not a first run, trace the pipeline in order: screenshot output and actualDir, expected-image synchronization, snapshot-key selection, then publisher configuration.

Reg-suit compares current images in core.actualDir with expected images retrieved by its publisher plugin. Its documented workflow has synchronization, comparison, and publication stages. The exact error text and cause for a particular project cannot be determined without its logs and configuration. See the official Reg-suit README and project repository.

1. Decide whether this is a first run

Ask whether a prior run published snapshots for the key this run is using. If there is no baseline yet, new images on the initial run can be normal. In the official Puppeteer demo, the first run reports images as new and publishes them; a later run retrieves those snapshots as expected images.

• No prior baseline: review the new images and publish the intended baseline using your normal review process.
• A baseline should exist: continue through the checks below; do not assume the missing file means a visual difference.

2. Confirm screenshots exist in actualDir

core.actualDir is required. It must point to the directory containing the screenshots Reg-suit should compare. Confirm the capture step completed before Reg-suit starts and produced the expected files at that path.

1. Inspect the screenshot-generation job’s output and exit status.
2. List the generated files and check their names and extensions.
3. Resolve actualDir relative to the directory where Reg-suit runs, especially in CI.
4. Check whether a build or cleanup step removed or relocated the images before comparison.

A missing actual image and a missing expected image arise on different sides of the comparison. Establish which side is absent from the logs and report before changing configuration.

3. Locate the failing Reg-suit stage

The documented sequence is sync-expected, then compare, then publish. The run command combines the workflow. When troubleshooting, inspect the stages separately where practical so you can see where the expected files stop appearing.

Stage	What to check	What it tells you
Screenshot generation	Capture command, output directory, filenames	Whether actual images were created where Reg-suit expects them
sync-expected	Selected publisher, retrieval logs, local working directory	Whether prior snapshots were fetched
compare	Comparison logs and HTML report	Whether files were absent or present but visually different
publish	Publisher logs and storage destination	Whether current snapshots and reports were stored for future runs

Reg-suit documents workingDir as optional, defaulting to .reg. Inspect that directory after synchronization to determine whether expected images were retrieved. The comparison command can produce an HTML report; use it to distinguish missing files from images that exist but differ.

4. Verify the publisher and snapshot location

Publisher plugins retrieve prior snapshots and publish current snapshots and reports. Reg-suit documents S3 and GCS publisher plugins. Check the plugin configured under plugins and verify its storage settings against the location where the intended baseline was published.

• Confirm the expected publisher plugin is installed and selected.
• Check that bucket or storage location settings identify the same snapshot repository used by earlier runs.
• Check that CI credentials can read the existing snapshots and write new ones where required.
• Review synchronization and publication logs for access, location, or retrieval failures.

Do not assume that successful publication means a later run will fetch the same baseline: key selection and publisher retrieval path both affect which expected snapshot is used.

5. Check snapshot-key selection, especially in CI

The installed key-generator plugin determines which expected snapshot key Reg-suit looks up. Verify that the selected key points to the baseline you intend to compare against.

The official README documents a CI issue for the Git-hash plugin: a detached HEAD can prevent identification of the base commit. Its GitHub Actions example recommends making full branch history available with fetch-depth: 0 and attaching the branch in CI. Adapt the diagnosis to your own provider and branch rules; this example is not a universal CI configuration.

• Compare the key selected locally and in CI.
• Check whether the CI checkout is detached or has shallow history.
• Confirm the relevant base branch and commit are available to the key generator.
• Check whether a fork, pull request, or branch-specific publisher path changes the key or retrieval target.

6. Review configuration without changing comparison thresholds

The README lists these core options: actualDir, workingDir, thresholdRate, thresholdPixel, enableAntialias, ximgdiff, and concurrency. Publisher settings belong under plugins and depend on the selected plugin.

For a missing-file problem, first verify paths, synchronization, keys, and publisher settings. thresholdRate and thresholdPixel control tolerated visual differences; they do not make an expected image file appear. Changing thresholds is not a fix for failed retrieval.

Common symptoms and fixes

Symptom	Likely area to investigate	Next step
Every image is reported as new on the first run	No baseline has been published yet	Review the images and publish the intended initial baseline.
Local comparison works, CI reports missing references	Different key, checkout history, branch attachment, credentials, or working directory	Compare local and CI keys and inspect sync logs and CI checkout configuration.
Actual screenshots are absent	Capture step or actualDir	Confirm capture succeeded and writes files to the configured path before Reg-suit runs.
Synchronization completes but expected files are absent	Publisher plugin, storage path, or selected key	Check plugin configuration and whether the chosen key has a baseline at that location.
Images appear in the report but are marked different	Visual comparison result	Review the HTML report and decide whether the difference is an intended change before updating the baseline.
Publication appears successful but next run cannot retrieve snapshots	Publisher destination or key mismatch	Verify both the published location and the next run’s retrieval path and key.

Safe recovery checklist

1. Determine whether a baseline exists for the selected key.
2. Confirm actual screenshot files exist in actualDir.
3. Run or inspect synchronization and check the expected files in the working directory.
4. Verify the key-generator result and publisher location, credentials, and plugin settings.
5. Inspect the comparison report if files were found but differ.
6. Publish or update a baseline only after reviewing that it is the intended reference.

Performance, reliability, and cost considerations

The supplied Reg-suit documentation identifies concurrency as a core setting, but it does not provide benchmark figures for this troubleshooting case. Increasing concurrency will not repair a wrong key, absent baseline, incorrect path, or inaccessible publisher. First identify the failing stage; then tune concurrency only if comparison throughput is the actual issue.

For reliable CI runs, keep screenshot generation, synchronization, comparison, and publication visible in logs; make sure the checkout contains the history needed by the chosen key generator; and preserve the same intended publisher location across runs. The research sources do not specify storage prices or a universal cost model, so check your selected storage provider and CI usage for project-specific costs.

Or skip the browser setup

If your immediate task is to generate the actual screenshot inputs for a visual regression workflow, ScreenshotNeo is a website screenshot API and MCP server. Reg-suit still handles expected-image synchronization and comparison; this API call supplies a screenshot rather than configuring a browser capture stack.

See the ScreenshotNeo API documentation. Replace the target URL and API key with your values:

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

• Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
• Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status.
• An MCP server gives Claude, Cursor, and other MCP clients screenshot, page-info, and PDF capture tools.
• The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 shots; every feature is on every plan.

Sign up for ScreenshotNeo and get 1,000 free screenshots a month, with no card required.

FAQ

Does a missing reference always mean Reg-suit is broken?

No. An initial run may have no previous baseline. Check whether one exists for the selected key before treating the result as a failure.

Should I increase the visual difference threshold?

Not to resolve a missing reference file. Threshold settings affect tolerated image differences, not retrieval or file paths.

What details help diagnose a specific incident?

Share the Reg-suit version, exact error and surrounding logs, relevant configuration with secrets removed, CI provider and checkout behavior, selected key, whether the issue occurs locally, and whether a baseline is known to exist.