Troubleshooting
Check config first:
npx vizzly doctorAdd --api to check auth and connectivity:
npx vizzly doctor --apiAuthentication
API token required
Sign in and link the project locally:
npx vizzly loginnpx vizzly project link your-org/your-projector:
export VIZZLY_TOKEN=vzt_your_token_hereInvalid or expired API token
Check that uploads use a token for the right project. Replace an expired or
revoked token in VIZZLY_TOKEN, or relink locally with vizzly project link.
For account commands, check vizzly whoami and sign in again if the session
has expired. See Authentication.
Configuration
Invalid apiUrl
Use a full HTTP or HTTPS URL:
export default { apiUrl: 'https://app.vizzly.dev',};Invalid threshold
Threshold must be 0 or higher.
export default { comparison: { threshold: 2.0, },};Local server issues
Port already in use
Pick a different port:
npx vizzly tdd start --port 47393or:
npx vizzly run "npm test" --port 47393TDD mode issues
Cloud baseline flags fail locally
--baseline-build and --baseline-comparison need authentication. Plain local TDD mode does not.
Local files look wrong
Inspect .vizzly/ and confirm you have the expected local artifacts:
baselines/current/diffs/report/
Upload and CI issues
Tests passed but screenshots are missing
Start with the final vizzly run summary:
Screenshots: 4 captured, 2 uploaded, 1 reused, 1 failedcaptured counts screenshots received by the local server. uploaded and reused count successful cloud results. A reused screenshot already exists in Vizzly, so it doesn’t need another upload.
If any uploads fail, the CLI logs each screenshot’s name and the reason at the normal log level. It continues accepting later screenshots and lets your tests finish. The Vizzly build is marked as failed; if the API can’t save that status, the CLI warns about that too.
An upload failure doesn’t change your test command’s exit code. It also skips --wait, since the visual build is incomplete. For automation, inspect upload failure details instead of relying on a green test job.
Fix the reported problem and rerun the capture command. If you’re using parallel shards, check each shard’s summary and use a new parallel ID for the rerun.
An image or screenshot name is rejected
Check the cloud screenshot requirements. The error should identify the problem, such as an image exceeding the dimension limit or a file that can’t be decoded.
For a dimension error, capture a smaller region or split the page into named sections. Use the image’s actual pixel dimensions when checking the limit; browser CSS dimensions can differ. Re-encoding alone won’t make an image shorter.
Names can include punctuation such as the colon in Checkout: empty cart. Keep them stable for baseline matching. See upload errors and API codes for image-specific fixes.
Uploads fail because the API is unavailable
Check vizzly doctor --api and the upload warning. Once connectivity is restored, rerun the capture command. A passing test job doesn’t mean those screenshots were uploaded later.
Build never shows up
Check these in order:
- auth is valid
- the command actually uploaded screenshots
- you are looking at the right project
Preview upload cannot find a build
Pass one explicitly:
npx vizzly preview ./dist --build <build-id>If the screenshots came from parallel shards, finalize that parallel ID first,
then pass the finalized build ID to preview. The preview command itself does
not accept --parallel-id.
Context and API requests
A cloud response includes more data than you need
Use the API schema to find an operation that returns the data you need:
npx vizzly api schema --jsonnpx vizzly api schema sdk.listBuilds --jsonUse the operation’s method, parameters, and request body when you call it. See API schema and requests.
Local and cloud results are different
TDD screenshot commands read saved files from .vizzly/. Cloud API requests read
Vizzly data using your account login or project token. Inspect local comparisons with:
npx vizzly tdd screenshots list --jsonnpx vizzly tdd screenshots show <comparison-id> --image all --jsonThe saved report might be older than your UI change. Rerun the visual tests
if you’re unsure. Local failed means the image changed; cloud review state
comes from a separate review decision.
An image or comparison is missing
Check the image’s exists flag before opening the file. New captures may have
no baseline or diff. In cloud results, comparison_id can be null while processing
or after a failure. Use sdk.getScreenshotImage to get the capture itself until
you have a comparison ID.
A build completed but the command still failed
A build can finish processing and still need visual review. Check the returned build before treating a nonzero exit code as a timeout.