BackstopJS "Reference image not found, run reference" in CI

BackstopJS test compares against reference images in backstop_data/bitmaps_reference. If that folder is empty for a scenario, there is nothing to compare and Backstop tells you to run reference first.

What this error means

The backstop test step fails with "Reference image not found, please run backstop reference." The bitmaps_reference directory is missing or was not committed to the repo.

Reference image not found for "Home". Run `backstop reference` to create it.

Common causes

References never generated for a new scenario

A scenario was added to backstop.json, but backstop reference was not run to create its baseline image.

The reference bitmaps are gitignored

backstop_data/bitmaps_reference is excluded from version control, so the CI checkout has no baselines to compare against.

How to fix it

Generate and commit references

1. Run backstop reference in the CI container so bitmaps match the runner.
2. Confirm bitmaps_reference is not gitignored.
3. Commit the reference images.

npx backstop reference
git add backstop_data/bitmaps_reference

Keep only the test output ignored

Ignore the generated bitmaps_test output, but commit bitmaps_reference as fixtures.

# .gitignore
backstop_data/bitmaps_test/
backstop_data/html_report/

How to prevent it

• Run backstop reference for every new scenario.
• Commit bitmaps_reference; ignore only bitmaps_test.
• Generate references in the CI container.

Related guides