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, not pointed at this repo, or not connected to this project. Uploads work with only the API key, but the check and PR comment need the App, and they only post through the installation connected to the project, never one found from the repo name. Install or connect it from your project settings and select the repo - see step 4 of the Storybook quickstart.

UI Verify will not connect a GitHub App installation it cannot safely match to your team, for example one another team already connected, or an older installation it has no record of you making. You see a notice that it couldn't connect. Email support@uiverify.ai with your project and we will look into it.

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 directory you uploaded holds no captures. For Vitest or Playwright, the tests ran without the UI Verify capture SDK writing anything: check that Vitest runs in browser mode with uiverifyPlugin(), or that your Playwright tests import from @uiverify/playwright, then look inside ./uiverify-archive/snapshots before uploading. For Storybook, point --static-dir at your storybook build output. The failed build shows the reason on the build page and in the PR check. Fix the setup and upload again.

The UIVERIFY_API_KEY is missing or wrong. Locally, pass it inline (UIVERIFY_API_KEY=your_key npx -y uiverify@1.7.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, use the two-workflow setup in Visual testing on open source repos: the fork's run saves its capture, and a separate workflow on your default branch uploads it with your key.

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.