Troubleshooting

QualityGate fails closed: when it cannot give a trustworthy answer, the step fails and says why. Find the message from your CI log below.

Authorization denied

The log shows QualityGate authorization denied: <reason>.

Reason	What it means	Fix
invalid_api_key	The key does not match any project.	Check the secret name and value, and that the key was copied in full.
key_revoked	The key was revoked in the app.	Create a new key and update the CI secret.
plan_inactive	The organization has no active plan.	Check Billing.
repo_not_allowed	The repository identity did not match the project.	Use the key that belongs to this repository’s project, and check its repository path or UUID. For keyless runs, confirm the repository was added through Connect GitHub, the GitHub App is still installed on it, and the workflow grants id-token: write.
domain_not_allowed	The URL’s host is not in the project’s allowed domains.	Add the host, or a *. pattern covering it. *.example.com does not cover example.com itself.
bundle_not_allowed	Your plan does not include the requested bundle.	Use a11y, or upgrade under Billing.
quota_exceeded	The month’s runs, or scheduled scans, are used up.	Wait for the reset on the 1st (UTC), or upgrade. Billing shows usage.

The run could not start

Action input 'api_key' is required unless the workflow grants 'id-token: write' and the repository is connected through the QualityGate GitHub App. Either add api_key, or add id-token: write to the workflow’s permissions and connect the repository through the GitHub App.

QualityGate supports pull_request, push, and schedule events only. The workflow was triggered by another event, such as workflow_dispatch or deployment_status. See Supported triggers.

Could not reach the QualityGate authorization service. The runner could not connect to https://api.qualitygate.dev. Check the runner’s outbound network access and proxy settings. Nothing was counted.

Action input 'fail_on' must use 'critical=N,serious=N' or 'regression', with non-negative integers. Absolute limits need both critical and serious, for example critical=0,serious=0.

The preview never became ready

Preview URL was not ready within 120 seconds. QualityGate waits for a 2xx response before scanning. Common causes:

• The preview is still building. Raise wait_timeout, for example to 600, or make the scan job depend on the deploy job.
• The preview is protected. Vercel Deployment Protection, Netlify password protection, basic auth, and IP allowlists all return 401 or 403. Allow public access to previews. See Preview deployments.
• The URL is wrong. A typo in a predictable preview address returns 404 forever. Open it in a browser from the pull request.
• The page redirects to a login screen that returns an error status.

Nothing is counted when the preview never becomes ready.

The scan failed

QualityGate scan failed: browser_launch_failed. The runner has no Chromium that QualityGate can use. On GitHub Actions, add this step before the QualityGate step:

- run: npx -y playwright@1.61.1 install --with-deps chromium

If --with-deps fails because apt-get cannot update a third-party package source on the runner, retry the job, or drop --with-deps on runners that already have Chromium’s system libraries.

QualityGate scan failed: page_load_failed. The browser could not load the page, for example because it timed out or the connection was refused. Check that the URL loads from outside your network.

QualityGate scan failed: performance_engine_unavailable. The perf bundle could not install Lighthouse. It needs npm and access to the npm registry from the runner.

A scan that fails after authorization releases its reserved run, so it does not count against your allowance.

No pull request comment

The job summary always has the full report, even when the comment is missing.

• Without the GitHub App, the workflow needs pull-requests: write and env: GITHUB_TOKEN: ${{ github.token }} on the QualityGate step.
• Fork pull requests get a read-only token, so the comment cannot be posted. See Fork pull requests.
• On GitLab, QUALITYGATE_GITLAB_TOKEN needs the api scope and a role that can comment on merge requests. A requested note that cannot be posted fails the job.
• On Bitbucket, QUALITYGATE_BITBUCKET_TOKEN needs pullrequest:write.
• Push and scheduled runs never comment, by design.
• With a matrix, all runs share one comment. See Multiple pages and sites.

Regression mode never fails

If every regression run reports that no comparison was possible, no baseline exists yet for that page and bundle. Baselines are recorded by runs on the project’s default branch: add a push trigger for it, and make sure the push run scans the same page path with the same bundle. See Recording a baseline.

Still stuck?

Email hello@qualitygate.dev with a link to the failed CI run and the project name. Never send your API key.