Troubleshooting UI Verify

Most first-run problems fail quietly - the upload succeeds and something downstream is just missing. Here are the ones we see most, each with the reason and the fix.

The GitHub App is not installed, or not pointed at this repo. Uploads work with only the API key, but the check and PR comment need the App. Install it from your project settings and select the repo - see step 4 of the Storybook quickstart.

Installing @uiverify/playwright is not enough - you have to swap the import in your tests to import { test, expect } from "@uiverify/playwright". Without the swap, nothing is written to ./uiverify-archive and the upload has an empty directory. See step 2 of the Playwright quickstart.

Your CI is checking out a shallow clone, so UI Verify cannot resolve the right baseline from your branch history. Add fetch-depth: 0 to your actions/checkout step. If only one or two stories look off, the branch may just be behind - see Baselines and branches.

A clean CI runner has no browsers installed. Add npx playwright install --with-deps before you run your tests, as in the Playwright quickstart CI workflow.

The UIVERIFY_API_KEY is missing or wrong. Locally, pass it inline (UIVERIFY_API_KEY=your_key npx -y uiverify@latest upload ...) or export it first; in CI, add it as a repository secret and reference it under env. The key is per project - copy it from that project's settings.

It needs Storybook's dependency graph, which only exists when you build with --stats-json. Without preview-stats.json the flag safely falls back to a full render. See Skip unchanged stories.