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.

render() from vitest-browser-react is async, so a takeSnapshot() or end-of-test capture that runs before it commits archives an empty body over your stylesheet - a blank screenshot that then becomes a blank baseline. Await the render: await render(<Component />). See step 2 of the Vitest 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.

You uploaded with a capture SDK, or a bundle format, that does not match how the project was created. A UI Verify project has one capture type, fixed when you create it: Storybook, Playwright, Vitest, or custom screenshots. Uploading a Playwright or Vitest archive to a custom-screenshots project, or the wrong SDK for the type, is rejected up front with a message naming the type the project expects, instead of failing later mid-render. The fix is to create a project of the matching type and upload to that one. See What is visual regression testing for the four types.

The UIVERIFY_API_KEY is missing or wrong. Locally, pass it inline (UIVERIFY_API_KEY=your_key npx -y uiverify@1.4.0 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.

GitHub withholds repository secrets from workflows triggered by a forked-repo pull request, so UIVERIFY_API_KEY is empty and the upload is skipped. This is expected, and it affects any secret-based CI - it does not happen for branches pushed to the same repo. If you take outside contributions, run the upload on push to your own branches, or gate the step so it only runs when the PR is not from a fork.

It needs a module dependency graph in the uploaded bundle (preview-stats.json). Storybook only writes one when you build with --stats-json; a Vitest archive needs @uiverify/vitest 1.1+, which writes it automatically; a Playwright archive never has one, so the flag is ignored there. Without the graph the flag safely falls back to a full render. See Skip unchanged stories.