Ask the Community
Diagnose issues using Percy Doctor
Use the Percy Doctor CLI command to diagnose connectivity, authentication, and configuration issues before contacting support.
Percy Doctor is a built-in CLI diagnostic command that checks your environment and validates key Percy dependencies, including token authentication, network connectivity, SSL certificates, proxy configuration, Percy config file, CI environment metadata, and browser network access. Run it when a Percy build fails unexpectedly or while setting up Percy in a new environment.
Percy Doctor is available in @percy/cli version 1.31.10 or later:
- Run
npx percy --versionto check your current version. - To upgrade, run
npm install --save-dev @percy/cli@latestoryarn add --dev @percy/cli@latest.
Overview
Percy Doctor performs the following checks in sequence:
| Check | What it validates |
|---|---|
| Configuration | Validates Percy config file presence, syntax, version, and token type compatibility |
| CI Environment | Detects CI system and validates commit SHA, branch name, and parallel build settings |
| Environment Variables | Validates PERCY_* variables, PERCY_PARALLEL_TOTAL format, and TLS settings |
| Network Connectivity | Checks reachability of percy.io, www.browserstack.com, and hub.browserstack.com
|
| SSL / TLS | Validates certificate for percy.io; detects proxy certificate interception |
| Proxy Detection | Detects proxy configuration using environment variables, system settings, response headers, and WPAD/PAC |
| Token Authentication | Validates PERCY_TOKEN against the Percy API and identifies project type and role |
| Browser Network | Validates end-to-end connectivity through headless Chrome, including proxy or PAC resolution |
Percy Doctor classifies each finding as pass, warn, fail, or info. Failures and warnings include actionable suggestions.
Command usage
Run the full diagnostic to probe all required domains, launch headless Chrome, and validate your token against the Percy API:
This diagnostic takes approximately 30 seconds to complete.
Quick mode
Run quick mode to check connectivity, SSL, and token authentication in approximately 4 seconds:
This mode is useful for fast triage in CI pipelines or when you need a quick network and token check.
Options
Percy Doctor supports the following command-line options to customize diagnostic behavior:
| Option | Default | Description |
|---|---|---|
--quick |
Off | Run only connectivity, SSL, and token checks (~4 seconds) |
--proxy-server <url> |
Auto-detected | Forces all diagnostic requests through a specified proxy |
--url <url> |
https://percy.io |
Overrides the target URL for connectivity and browser checks |
--timeout <ms> |
10000 |
Sets the per-request timeout in milliseconds (maximum: 300,000) |
--output-json <path> |
Writes the full structured report to a JSON file | Â |
-v, --verbose |
Off | Enables detailed debug output |
-h, --help |
— | Displays help text |
Example: Save a JSON report for support
Generate a JSON report that you can attach when raising a support ticket:
The generated file contains the complete finding set with metadata, statuses, and suggestions.
Auto-Doctor on build failure
When a Percy build fails, Percy can automatically run a quick diagnostic and print findings inline in your CI logs. Enable this feature by setting the PERCY_AUTO_DOCTOR environment variable:
Percy automatically captures diagnostic findings and includes them in your CI logs, helping you identify and resolve issues faster. For additional troubleshooting help, contact BrowserStack support.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!