SonarQube — Quality Gates, Web API, Administration, Errors and Mistakes

How SonarQube Server computes quality gates, how to read them through the Web API, and how to run the server. Covers the production errors, the mistakes that fake a green gate, and how to investigate a bug static analysis missed.

Overview

SonarQube Server is usually trusted as a yes or no answer: the quality gate passed, so the code may ship. In production the failures are rarely in that answer itself. They are in what fed it: a scanner that analyzed the wrong branch, a background task that failed so the dashboard still shows yesterday, a coverage report that was never found, a new code definition that hides the change, an issue someone marked Accepted to get a release out, or an exclusion pattern that removed the file that later broke.

This page covers how the gate is computed, how to read it from the Web API, how to run the server (Compute Engine, Elasticsearch, database, upgrades, tokens, webhooks), the errors you will see, and the mistakes that turn a green gate into a false promise.

Both the version and the edition change what you can do. Up to 10.8 SonarQube Server used MAJOR.MINOR.PATCH; since then it uses YYYY.ReleaseNumber.PatchReleaseNumber, with a release every two months and two Long-Term Active (LTA) releases a year. The current documentation describes 2026.5 LTA (the previous LTA is 2026.1), and the Web API reference on next.sonarqube.com runs a 2026.6 build. Editions matter too: branch analysis, pull request analysis and pull request decoration need Developer Edition or higher; SonarQube Community Build does not have them.

> [!IMPORTANT] A green quality gate means the conditions you configured passed on the code that was analyzed, for the code SonarQube counted as new. Every one of those three clauses can be wrong without the gate turning red.

Symptom to first command

CI step reads the gate and gets NONE or a stale result — curl ... /api/qualitygates/project_status?projectKey=KEY then /api/ce/component?component=KEY — Reading the gate from the Web API
Scanner says EXECUTION SUCCESS but the project page did not change — Project Settings > Background Tasks, Show Error Details — Errors: gate not computed, background task failed
Scanner fails with PKIX path building failed, 401 or 403 — Check sonar.host.url, the token type and the CA truststore — Errors: scanner cannot reach or authenticate
Results land on the wrong branch, or no branches at all — Check sonar.branch.name and the edition — Errors: wrong branch, 0% coverage, new code
Coverage shows 0% — Scanner log for the coverage report path — Errors: wrong branch, 0% coverage, new code
Server will not start, es.log complains about vm.max_map_count — sysctl vm.max_map_count — Errors: Elasticsearch
Indices read-only, web and CE errors — Disk usage of the data directory — Errors: Elasticsearch
Gate green for months, a bug shipped anyway — /api/rules/search, /api/qualityprofiles/search, /api/issues/search — What static analysis can and cannot catch

What you will be able to do

Explain how a scanner run becomes a quality gate status: quality profiles, rules, issues, new code, conditions, and the Compute Engine background task.
Write the curl command that reads a project, branch or pull request gate status, parse it with jq, and say exactly what OK, ERROR and NONE mean according to the API reference.
Operate the server: watch the Compute Engine queue, meet the Elasticsearch host requirements, back up and restore, plan an LTA upgrade path, manage tokens, permission templates and webhooks.
Diagnose the common failures: gate not computed, background task failed, scanner cannot connect, wrong branch, 0% coverage, misconfigured new code, Elasticsearch bootstrap checks and read-only indices.
Handle the process side: a hotfix blocked by a code smell, broad Accept and False positive decisions, exclusions that hide code, a leaked admin token.
Investigate a missed bug and separate a configuration gap from a limit of static analysis.

Key concepts

Quality gate: A set of failing conditions (metric, operator, threshold) on new or overall code. If any condition is met the gate fails. Assigned per project, never per branch.
Sonar way gate: The built-in, read-only default gate: no new issues, all new hotspots reviewed, new coverage of at least 80.0%, new duplication of at most 3.0%.
New code definition: Previous version, Number of days (default 30, max 90), Specific analysis (branch only, API only) or Reference branch. Branch overrides project overrides global; the global default is Previous version.
Issue backdating: A new issue takes the last commit date of its line when SCM data exists, so issues on untouched lines are old code. Applied to all new issues since 2026.5.
Background task: The Compute Engine job that processes an uploaded analysis report. Reports are processed serially and results, including the gate, appear only after the task completes.
project_status NONE: Per the API reference, the status returned when there is no quality gate associated with the analysis. Not a pass.
Fudge factor: Coverage conditions are ignored under 20 new lines to cover and duplication conditions under 20 new lines; on by default, set with sonar.qualitygate.ignoreSmallChanges. Issue conditions are never relaxed.
Quality profile: The active rules per language. Since 2026.5 the built-ins are Sonar way core (default on new installations), extended and comprehensive.
MQR mode versus Standard Experience: MQR classifies each rule by its impact on security, reliability and maintainability with separate severities; Standard Experience uses Bug, Vulnerability, Code Smell and Hotspot types.
Project analysis token: A token that can only analyze one project, encouraged by SonarSource so a leak exposes a single project, unlike a user token that carries all its user's permissions.

When to use it

You are wiring a SonarQube quality gate into CI and need the pipeline to fail on anything other than a computed, passing gate.
A release is blocked by the gate under time pressure and you need a decision that is fast, recorded and does not weaken the gate for everyone.
You operate a self-managed SonarQube Server and need to keep the Compute Engine, Elasticsearch and database healthy through upgrades.
Results look wrong: wrong branch, 0% coverage, stale dashboard, or a gate that is green while issues obviously exist.
A defect reached production despite a green gate and you must show whether configuration or static analysis itself was the gap.
You are preparing for a DevOps or platform interview that covers code quality gates and CI governance.

Interview questions

Can you write a curl command to programmatically check a project's current quality gate status via the sonarqube web API, and explain what a response of status None means
A critical prod hotfix is ready to ship but the sonarqube quality gate fails on a new code smell (not a bug) introduced by the hotfix itself. The fix needs to go out in next 30 mins. What do you actually do?
Sonarqube's quality gate has been green for months, but a serious bug just shipped to production that, in hindsight, should have been obviously catchable by static analysis. How do you investigate whether this is a sonarqube configuration gap or an inherent limitation of static analysis.
How is the quality gate computed differently for a branch and for a pull request, and what is the fudge factor?
The scanner log says EXECUTION SUCCESS but the dashboard did not change and the pipeline's gate check passed on old data. Explain and fix.
How would you fail a CI pipeline on a red quality gate, and what are the trade-offs between sonar.qualitygate.wait, webhooks and polling the API?
SonarQube will not start after moving it to a new Kubernetes cluster, and es.log mentions vm.max_map_count. What do you do?
An admin's user token was pasted into a public CI log. Walk through your response.
Coverage on new code shows 0% although the tests run in the same pipeline. What do you check?
How do you plan an upgrade from SonarQube 9.9 LTA to the current LTA without losing data?
How do you prove nobody weakened the quality gate or the rules to get a release out?