Troubleshooting

The ten most common ways a first run goes sideways, in roughly the order they tend to come up. If you're stuck, scan this page before opening an issue — odds are good your exact problem is one of these.

"The editor opens to a blank screen"

You don't have a project open yet. The empty state shows two cards: Create sample project and Open a folder. Pick one. (If neither card is showing, you're on the wrong screen — the editor's window title should say Provar with no project name.)

"My API key isn't being accepted"

The CLI reads the API key from ~/.provar/settings.yml. If the file doesn't exist yet, the CLI ships sensible defaults on first run — just edit it and add an apiKey for the provider you want to use. The compile step validates the key before doing any work; if the active provider has an empty key, it fails with a clear error pointing at the file. From the editor, open the Settings dialog (Provar → Settings…), re-paste the key, hit save, close the dialog, reopen the file.

"Compile is taking forever"

The first compile of an action is an LLM round-trip — figure on 10–30 seconds per action. A 50-action file takes a few minutes. This is normal. Subsequent compiles are incremental: only the actions you've actually changed re-run. So if you regenerate one action, you're waiting 15 seconds, not ten minutes.

"The browser never opens"

The CLI ships its own browser bundle — there's no separate browser install step. If a run fails with "failed to launch browser", the most common cause is a missing system library (libnss, libgbm, libdrm on Linux). On Linux runners, install the deps before invoking the CLI: sudo apt-get install -y libnss3 libgbm1 libdrm2 or the equivalent for your distro.

"My action passed visually but failed the snapshot diff"

The page rendered slightly differently than last time — a different timestamp, a stray ad, an animation frame caught mid-fade. The editor's run panel shows the diff side-by-side. If the change is fine, click Accept new snapshot and the new image becomes the baseline. If it isn't, regenerate the action.

"The editor crashes when I switch files"

Known issue with the file-switch screenshot race (see docs/TODOS.md T010). The workaround is to save the file and reopen it. The fix is queued for the next release — we know about it, and we're sorry it's annoying.

"I typo'd a CLI subcommand and the command exited 0"

Fixed in the current build: unknown subcommands now exit 2 with a helpful message that includes the typo and the closest match. If you're on an older build, git pull and try again.

"Tests pass locally but fail in CI"

Nine times out of ten it's one of two things. Missing browser system libraries — install the deps for your runner image (see "The browser never opens" above). Missing API key — ship it as a CI secret and write it into ~/.provar/settings.yml in a pre-step; don't bake the key into the workflow file. The CI page has the full recipe.

"I want to undo accepting a baseline"

Baselines are PNG files in .provar/screenshots/. git revert the ones you want to roll back, re-run, and accept the right snapshot. Same as reverting any other tracked file — that's the whole point of storing baselines in git.

"Where do I report a bug?"

github.com/thani-sh/provar/issues. Include the editor version (Provar → About), the file, and the failing run's output. Screenshots of the run panel help too. We read everything; the more context the better.