Reference Guide
SonarQube Technical Debt Metrics Explained
You opened SonarQube and see a dashboard full of numbers. Here is what each metric actually means, what thresholds matter, and what each score costs your team in real dollars.
Updated 16 April 2026
Technical Debt Ratio
Formula
debt_ratio = (remediation_cost / development_cost) * 100
Where remediation_cost is the estimated time to fix all maintainability issues, and development_cost is the estimated time it took to write the code.
The technical debt ratio is SonarQube's single most important metric. It answers: “What percentage of the effort that went into building this code would be needed to fix all its quality issues?” Each rating maps to a SQALE band:
0 - 5%
Technical debt is negligible relative to development cost
5 - 10%
Manageable debt. Standard for well-maintained projects
10 - 20%
Accumulating debt. Review sprints recommended quarterly
20 - 50%
High debt. Feature velocity is measurably impacted
50%+
Critical. Code debt is actively blocking delivery
What “Good” Looks Like by Project Maturity
| Stage | Target Rating | Rationale |
|---|---|---|
| Startup / MVP | B-C | Speed matters more than perfection. Debt is intentional and acknowledged. |
| Growth | A-B | Team is scaling. New engineers need a navigable codebase. |
| Enterprise | A | Compliance, audit, and regulatory pressure demands low debt. |
| Legacy (improving) | C (trending to B) | Absolute score matters less than the trend. Improving is what counts. |
Reliability Rating
Reliability measures bugs: code that is demonstrably wrong and will produce incorrect behaviour at runtime. Each severity level maps directly to production impact.
No bugs
Minimal production risk. Deployments are routine.
At least 1 minor bug
Low risk. Minor bugs rarely cause incidents.
At least 1 major bug
Moderate risk. Major bugs can cause partial outages or data issues.
At least 1 critical bug
High risk. Critical bugs cause service degradation or data loss.
At least 1 blocker bug
Severe risk. Blocker bugs cause full outages or security breaches.
Security Rating
Security rating reflects confirmed vulnerabilities in the code. Separate from security hotspots (which are potential vulnerabilities requiring manual review). The rating is based on the worst vulnerability found.
No vulnerabilities
No known security exposure from code-level issues.
At least 1 minor vulnerability
Low-severity issues. Information disclosure or minor input validation gaps.
At least 1 major vulnerability
Exploitable under specific conditions. Requires patching within sprint.
At least 1 critical vulnerability
Actively exploitable. Patch within days, not weeks.
At least 1 blocker vulnerability
Immediate risk. Stop shipping until resolved.
Cognitive Complexity vs Cyclomatic Complexity
SonarQube uses cognitive complexity (introduced in 2017) rather than the older cyclomatic complexity metric. Cognitive complexity better reflects how hard code is for humans to understand, not just how many execution paths exist.
Cognitive Complexity
Measures how difficult code is to understand. Penalises nesting, break-in-flow statements, and recursion. A function with nested if-else chains scores much higher than the same logic expressed with early returns.
Used by: SonarQube, SonarCloud
Cyclomatic Complexity
Counts independent execution paths through a function. A 10-branch switch statement and 10 nested if-else blocks score the same, even though the switch is far easier to read.
Used by: ESLint, CodeClimate, most older tools
Complexity Thresholds
1-15
Acceptable
Function is readable and maintainable
15-25
Review
Consider refactoring to reduce nesting
25+
Refactor
Function is too complex to safely modify
Code Duplication
SonarQube flags blocks of 10 or more duplicated lines (or 100+ duplicated tokens, depending on language). Duplication percentage is the ratio of duplicated lines to total lines. The real cost is not the duplicate code itself but the bugs that appear when one copy is updated and the other is not.
<3%
Excellent
3-5%
Acceptable
5-10%
Warning
10%+
Critical
Quality Gates
A quality gate is a set of conditions that new code must pass before it can be merged. SonarQube's default gate (called “Sonar way”) checks new code only, not the entire codebase. This is intentional: it prevents new debt without requiring you to fix everything at once.
Default Quality Gate Conditions
| Condition | Threshold | Applies To |
|---|---|---|
| Coverage on new code | >= 80% | New code only |
| Duplication on new code | <= 3% | New code only |
| Maintainability rating | A | New code only |
| Reliability rating | A | New code only |
| Security rating | A | New code only |
| Security hotspots reviewed | 100% | New code only |
Why the default gate is too lenient for most teams
The default gate only checks new code, which means existing debt is never addressed. Consider adding overall project conditions: a maximum technical debt ratio for the entire codebase, a minimum overall coverage threshold, and duplication limits on all code. Start lenient and tighten over time.
Configuring Remediation Cost
SonarQube's default development cost is 30 minutes per line of code. This is the denominator in the debt ratio formula and directly affects every metric on your dashboard. If your actual cost per line is higher (larger team, more review, stricter compliance), the default underestimates your debt.
How to calibrate
1. Estimate total development hours for a recent project
2. Count lines of code delivered (use cloc or tokei)
3. Divide: hours / lines = your actual cost per line in hours
4. Convert to minutes and update in SonarQube admin
Path: Administration > Configuration > General > Technical Debt > Development cost