Skip to content
Latest

Troubleshooting

Check config first:

Terminal window
npx vizzly doctor

Add --api to check auth and connectivity:

Terminal window
npx vizzly doctor --api

Authentication

API token required

Sign in and link the project locally:

Terminal window
npx vizzly login
npx vizzly project link your-org/your-project

or:

Terminal window
export VIZZLY_TOKEN=vzt_your_token_here

Invalid 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:

Terminal window
npx vizzly tdd start --port 47393

or:

Terminal window
npx vizzly run "npm test" --port 47393

TDD 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 failed

captured 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:

  1. auth is valid
  2. the command actually uploaded screenshots
  3. you are looking at the right project

Preview upload cannot find a build

Pass one explicitly:

Terminal window
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:

Terminal window
npx vizzly api schema --json
npx vizzly api schema sdk.listBuilds --json

Use 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:

Terminal window
npx vizzly tdd screenshots list --json
npx vizzly tdd screenshots show <comparison-id> --image all --json

The 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.

Next steps