Reg-suit Error: No Image Files Found in the Actual Directory
This reg-suit error usually means its configured actualDir has no readable images. Check the config, capture output, and run order before comparing snapshots.
Short answer: reg-suit’s configured core.actualDir is probably empty, points to a different directory than the one receiving your screenshots, or is being checked before image generation finishes. That is a diagnostic inference: the official sources available for this guide document actualDir and the comparison workflow, but do not document this exact error wording or confirm its internal trigger.
Check the configuration file selected for the run, verify that its actualDir contains the images you intend to compare, and make sure image generation completes first. A missing expected baseline is a separate issue: reg-suit’s documented workflow compares current images with expected snapshots, and its demo shows that an initial run can report supplied images as new items.
1. Confirm which configuration reg-suit is using
Reg-suit supports choosing a configuration file with -c or --config. In a project with multiple configurations, checking the wrong regconfig.json can make a correct directory look empty to the run.
# Run from the project directory and specify the configuration explicitly
npx reg-suit run --config ./regconfig.json
# Or use the short option
npx reg-suit run -c ./regconfig.jsonUse the command form supported by your installed reg-suit version and package setup. The important diagnostic is to identify the exact config file used by the failing run, including in CI.
2. Check core.actualDir
The reg-suit README documents actualDir as a required setting: it identifies the directory containing the images to test. Confirm that the configured path points to the output of your screenshot-generation step.
{
"core": {
"actualDir": "./screenshots"
}
}That snippet illustrates the setting; use the actual directory in your project. Resolve relative paths in the context of the command and environment that run reg-suit. If local runs work but CI fails, inspect the CI working directory and the path available inside the job or container.
3. Verify image generation and file visibility
Inspect the directory after your browser or other image-generation task has completed, in the same environment where reg-suit runs.
# Replace screenshots with the path configured in core.actualDir
find ./screenshots -type f -print
# Count files beneath the directory
find ./screenshots -type f | wc -lCheck that the process running reg-suit can read the files and that the generator writes into this directory rather than a similarly named output path. The official reg-viz Puppeteer demo prepares a screenshot directory and configures it as the actual-image directory; its workflow runs screenshot preparation before reg-suit.
4. Run generation before comparison
Order the CI steps so the current screenshots exist before reg-suit run starts. For example:
# Illustrative workflow: replace the generation command with your project script
npm ci
npm run capture-screenshots
npx reg-suit run --config ./regconfig.jsonIf screenshots are produced asynchronously, wait for that process to finish and check its exit status before starting reg-suit. A command that launches capture work in the background can let the comparison begin while the output directory is still empty.
5. Distinguish missing current images from a missing baseline
Reg-suit’s documented comparison workflow uses the current images in actualDir and expected snapshots fetched with sync-expected, then creates an HTML report. These inputs play different roles:
Current images in actualDir |
Expected snapshots | What to investigate |
|---|---|---|
| Absent | Either state | Capture output, configured path, run order, and file access. The current images are missing. |
| Present | Not yet available | This may be an initial comparison. The official demo shows supplied images can be reported as new items. |
| Present | Fetched | Run the comparison and inspect its HTML report for new or changed items. |
Do not treat a first run without prior snapshots as proof that actualDir is empty. First verify that current image files exist at the configured location.
6. Troubleshooting checklist
| Symptom | Likely cause | What to do |
|---|---|---|
| No files appear in the configured directory | The capture step did not run, failed, or writes elsewhere. | Check the capture command’s exit status and output path; run it before reg-suit. |
| Files exist locally, but CI reports none | CI uses a different working directory, filesystem, or config. | Print the selected config path and list the configured directory inside the job, after capture. |
| The directory exists but is empty at comparison time | Capture is still running or has not populated the directory. | Wait for capture to complete; avoid starting reg-suit concurrently. |
| Images are in a sibling or nested directory | core.actualDir does not match the generator output location. |
Correct the configured path or configure the generator to write to the intended directory. |
| Current images exist but are described as new | There may be no fetched expected snapshots yet. | Follow your project’s baseline setup and inspect the generated report. New items are distinct from an empty actual directory. |
| The exact error persists after files are confirmed | The available official sources do not specify the exact message’s version-specific trigger. | Record the reg-suit version, full command, config path, actualDir, file listing, and capture output for a focused investigation. |
7. Keep the capture step reliable
- Use one explicit output directory and set
core.actualDirto that location. - Make capture a completed prerequisite of the comparison step.
- In CI, inspect the directory from the same job or container that runs reg-suit.
- When debugging, preserve the exact command, selected configuration, and capture logs.
- Check current images and expected snapshots as separate inputs.
This sequence makes the diagnosis reproducible without assuming a specific undocumented cause for the exact error text.
8. Or skip the browser setup
If your goal is to create website screenshots for the actual-image directory, ScreenshotNeo can capture a page through one API request. Save the response into the directory configured as core.actualDir, and make sure that capture step finishes before reg-suit runs. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);For Node.js versions without Bun.write, write the response bytes using your preferred filesystem API. In every language, direct the output to the same location configured by core.actualDir. ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. ScreenshotNeo is a website screenshot API and MCP server from ScreenshotNeo. Sign up free and get 1,000 screenshots a month with no card.
Frequently asked questions
Does this error prove my expected baseline is missing?
No. Check for current files in actualDir first. A missing baseline and missing current images are different conditions in the documented workflow.
Can I use any directory name?
The directory name can follow your project’s layout, as long as the configured core.actualDir identifies the directory containing the current images.
What information should I include when asking for help?
Include the reg-suit version, exact command, selected config file, resolved actualDir, directory listing after capture, and the image-generation output.
Sources
- reg-viz/reg-suit official README — CLI configuration selection,
actualDir, and the documented comparison workflow. - reg-viz official repository packages and demos — Puppeteer demo workflow and prepared screenshot directory.
The sources document the configuration and workflow used for this diagnosis, but do not establish the exact internal trigger for the error wording in the title.
