Skip to content
Vizzly Docs

Troubleshooting

Start with the smallest useful check:

Terminal window
vizzly doctor

Add --api if the problem smells like auth or connectivity.

Terminal window
vizzly doctor --api

Authentication

API token required

Cloud upload commands need a project credential.

Fix it with either:

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

or:

Terminal window
export VIZZLY_TOKEN=vzt_your_token_here

Invalid or expired API token

For uploads, rotate the project token and update VIZZLY_TOKEN, or relink the checkout with vizzly project link. For account commands, sign in again with vizzly login. 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
vizzly tdd start --port 47393

or:

Terminal window
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
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
vizzly api schema --json
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

Local context reads saved data from .vizzly. Cloud requests read data from Vizzly using your account or project token. Keep the source clear when you use local context:

Terminal window
vizzly context build current --source local --json

The --agent options for context build and context comparison are deprecated in v0.37.x and will be removed in v0.38.0. Use API schema discovery for cloud requests. Local TDD results still work with vizzly context ... --json.

Fingerprint similarity fails locally

Fingerprint history is project-wide, so context similar needs cloud context:

Terminal window
vizzly context similar <fingerprint-hash> --source cloud --json \
  --project web --org acme

Local build, comparison, screenshot, and review-queue context remain available without cloud auth.

A build completed but the command still failed

Processing completion and visual success are separate. vizzly run --wait can confirm that the API finished processing and still exit non-zero because changed comparisons need review. Inspect the returned build instead of treating every non-zero exit as a processing timeout.

Next steps