Docs
Troubleshooting
Common problems and how to fix them.
Almost every page shows as changed#
Look at the height column. If after is taller or shorter, everything below the change shifts and counts as changed. Open the page in Swipe and find the first changed region on the rail: that's usually the one real change. Global changes, like a new header, also affect every page; mark one page as expected with a note and filter by a higher minimum %.
The same page changes between two runs of the same site#
Something on it isn't stable: a carousel, a random testimonial, a cookie banner, today's date. Hide it with "hideSelectors", block its host with "blockHosts", or give slow pages more time with "settleMs". Comparing a site against itself should give 0% everywhere, which is a good check when setting up a new project:
vdiff compare before before-again
Lots of pages say "capture failed"#
Something interrupted the network (Wi-Fi, VPN, sleep) or the site was too slow. Use ↻ Re-shoot N failed. If the same pages keep failing, open their URLs in a browser. Lowering "concurrency" helps with slow local sites; raising "timeout" helps with slow pages.
A page source fails#
WordPress, Statamic, Filament and Laravel sources start the app with PHP. The error says what's missing: no .env, no vendor/ (run composer install), or the wrong PHP version (set "php": "8.2" on the source). The Craft source connects to MySQL directly and needs the .env database settings.
Other sites' URLs are empty in setup#
visualdiff only guesses hosts it finds in your Herd links (<host>-fr.test). Fill them in, or leave them empty to skip those sites' pages.
A page shows the login screen#
It needs a session: run vdiff login <env>. See signed-in pages.
Certificate errors, or a URL isn't reachable#
visualdiff accepts local self-signed certificates (Herd, DDEV). Check the site loads in your browser at the URL in the config.
A branch won't prepare#
The log shows the command that failed. Common causes: the database server isn't running, the branch's composer install needs a different PHP version (set "php" in branches), or a migration fails on the copied database. Fresh database starts again from a new copy.
macOS says the app can't be opened#
Download visualdiff from visualdiff.app only. If macOS still blocks it, go to System Settings → Privacy & Security and choose Open Anyway.
Still stuck#
Email [email protected] with what you did and the log from the comparison.