Check system status
Check SonarQube CLI authentication, network settings, binaries, and integrations with `sonar system status`.
sonar system status gives you a single diagnostic view of your SonarQube CLI installation: whether your token is valid, which proxy, custom CA certificate, and client certificate settings the CLI resolved, which auxiliary binaries are installed, which integrations are configured, whether a configured MCP server has a ready container runtime, Vortex entitlement and usage when you're authenticated to an entitled connection, and whether a CLI update is available.
The command does not require authentication. It still reports whether saved credentials exist and, when possible, verifies the token against your SonarQube server.
Run the status check
sonar system statusThe output starts with a banner and a system check headline:
SYSTEM CHECK: Healthy when authentication and integration configuration look good.
SYSTEM CHECK: Issues found when the token is missing or invalid, when an MCP config file is present but malformed, when a configured MCP server has no ready container runtime, when
SONARQUBE_CLI_MCP_WSLis invalid on Windows, when an Antigravity secrets hook is installed but its configuration or backing script is invalid, when client certificate configuration is invalid, or when Vortex is installed but your connection is no longer entitled to it.
Authentication is reported as one of:
Not Set: no credentials from environment variables or a saved login
Active: token validated successfully
Invalid: token rejected by the server
Set Unverified: a token is stored but the server could not be reached to validate it. When the failure is due to a network or TLS problem, the output includes the underlying error message (for example, a connection timeout or certificate error).
What the report includes
Authentication
Active server URL, organization (SonarQube Cloud), and the current token state.
Binaries
Auxiliary tools the CLI downloaded (for example, the secrets engine and SCA scanner), their paths, versions, and whether a newer pinned version is available.
Cache
Whether log, SCA scanner cache, and global Git hook directories exist under ~/.sonar/sonarqube-cli/.
Integrations
Each sonar integrate install with its config path. Most agents report CONFIGURED, and OpenAI Codex reports INSTALLED with the recorded installation path. For Codex, the row also lists managed Sonar hook events when a managed requirements file contains Sonar hook commands. See Check Codex installation status. For most agents, MCP Server status is shown (not configured, configured, or invalid config). For Antigravity, Secrets Hook status is also shown when a secrets hook is recorded in state. When at least one MCP server is configured, one shared MCP Runtime line reports Docker, Podman, or nerdctl. See Check the MCP container runtime.
Network
Resolved proxy, custom CA certificate, and client certificate settings, including the configuration source (SONAR_* environment variables, stored network.* sonar config keys, or generic HTTPS_PROXY / NODE_EXTRA_CA_CERTS variables). Proxy URLs redact embedded credentials. When a client certificate is configured, the section lists the certificate path and, for PEM files, the key path. For PKCS#12 bundles (.p12 or .pfx), the key path is omitted and passphrase status is shown instead. When client certificate configuration is invalid, the section shows the error. When nothing is configured, the section reports that no advanced network configuration was detected. See Advanced network configuration for details. The SonarQube MCP Server launched by the CLI uses these settings. A note warns that not all CLI features currently honor proxy and certificate settings (for example, secrets hooks, Vortex context, and Software Composition Analysis). See environment-variables.md.
Vortex
When you're authenticated to a SonarQube Cloud or SonarQube Server 2026.5 or newer Enterprise or Data Center edition connection. Shows entitlement status and Vortex context usage against your plan limit. Omitted when Vortex does not apply to your connection. Status values: Active, Active (quota exhausted), Not entitled, Not available, Unknown (check failed), or Configured organization is not accessible with this token. Usage numbers appear on SonarQube (Server, Cloud) while you're entitled; they're omitted once your quota is exhausted. Entitlement loss marks the check unhealthy only when Vortex is installed through sonar integrate; quota exhaustion, check failures, and organization membership mismatches stay healthy. For a membership mismatch, run sonar auth status for next steps.
Recommendations
Suggested next steps such as sonar auth login, sonar update for an install-script copy, brew upgrade --cask sonarqube-cli for a Homebrew cask, or the original installation method for any other copy, fixing invalid client certificate configuration, re-running an integrate command to fix MCP or secrets hook configuration, installing or repairing Docker, Podman, or nerdctl when a configured MCP server has no ready runtime, or re-enabling Vortex, asking your administrator (SonarQube Server), or removing its integration when entitlement is lost.
When saved credentials are present, at least one integration shows MCP Server status configured, and the saved SonarQube Server or SonarQube Community Build URL uses a loopback host, Recommendations includes guidance that starts with MCP container networking:. A non-loopback mcp.container.serverUrl suppresses that guidance. It does not by itself mark the check unhealthy. See Reach a SonarQube Server on the same machine.
Check the MCP container runtime
When at least one integration shows MCP Server status configured, the report adds one shared line, MCP Runtime. An invalid or missing MCP configuration does not add that line by itself. The check asks Docker, then Podman, then nerdctl to run info. It does not download the MCP image, which means a ready runtime does not prove that the server will start.
A runtime that is not installed is skipped.
The first runtime whose
infocommand succeeds is ready. The line isMCP Runtime: READY (docker), or the same form forpodmanornerdctl.If
infodoes not answer within 3 seconds, the check stops on that runtime. The line isMCP Runtime: NOT RESPONDING (docker). It does not try the next runtime, and on Windows it does not try WSL.If
infofails and a later runtime answers, that later runtime is ready.If no
infocommand succeeds, the first installed runtime is not ready. The line isMCP Runtime: NOT READY (docker). A runtime that is on your PATH but fails bothinfoand--versionis still not ready when no later runtime answers.If every runtime is missing, the line is
MCP Runtime: NOT FOUND.
On Windows, a runtime reached through WSL adds via WSL, for example MCP Runtime: READY (docker via WSL). SONARQUBE_CLI_MCP_WSL selects native runtimes or WSL the same way as sonar run mcp. auto tries WSL only when Docker, Podman, and nerdctl are all missing. An installed native runtime that is not ready does not fall back to WSL.
Anything other than READY marks the check Issues found and adds one recommendation:
Not ready:
SonarQube MCP Server cannot start because docker is not ready. Start or repair it.The runtime name matches the line above, includingvia WSLwhen the check used WSL.Not responding:
docker is not responding to the runtime check. The MCP launcher may wait for it.Not found:
SonarQube MCP Server needs Docker, Podman, or nerdctl. Install and start one to use the MCP server.
On Windows, an invalid SONARQUBE_CLI_MCP_WSL value does not stop the command. There is no MCP Runtime line. Recommendations includes SONARQUBE_CLI_MCP_WSL must be auto, always, or never., and the check is unhealthy. macOS and Linux ignore the variable.
After sonar integrate for an agent, the same check runs when that agent's recorded install includes the MCP server. A missing or not ready runtime prints the recommendation on stderr as a warning, and the install still completes. On Windows, an invalid SONARQUBE_CLI_MCP_WSL value prints that error as a warning instead. A ready runtime prints no warning.
In JSON, mcpRuntime is null when no configured MCP server was checked, or when SONARQUBE_CLI_MCP_WSL is invalid on Windows. Otherwise it is an object:
Ready:
{ "status": "ready", "runtime": "docker", "viaWsl": false }Not ready, including through WSL:
{ "status": "not_ready", "runtime": "podman", "viaWsl": true }Not responding:
{ "status": "not_ready", "runtime": "docker", "viaWsl": false, "reason": "timeout" }Not found:
{ "status": "not_found" }
runtime is docker, podman, or nerdctl. reason is present only for a runtime that did not answer in time. healthy is false when the runtime is not ready, is not found, or the Windows variable is invalid.
Check Codex installation status
Other integrations report CONFIGURED. OpenAI Codex reports INSTALLED and includes the recorded installation path when one is stored:
The second line appears only when the managed requirements file contains Sonar hook commands. On macOS and Linux that file is /etc/codex/requirements.toml. On Windows it is %ProgramData%\OpenAI\Codex\requirements.toml. If ProgramData is unset, the path starts at C:\ProgramData.
The line lists only events whose commands are Sonar hooks. Commands for other tools in the same file are omitted. The CLI reads the file and does not run those commands. If the file is missing, empty, invalid, or has no Sonar hook commands, that is not an error: status prints only the INSTALLED line.
--format json lists Codex with the other integrations. It does not include the managed-hooks line.
For token verification details, see sonar auth status. For what reset clears, see Reset the CLI.
Machine-readable output
For scripts and automation, pass --format json:
--json has been deprecated since 1.9 and will be removed in a future version. It still prints the same JSON as --format json, and the CLI prints a deprecation warning on stderr. Use --format json instead. Passing --json selects JSON even when --format is also set.
The JSON document includes the CLI version, authentication summary, a network object (proxy URLs, noProxy list, CA certificate path, clientCertificate object with certificate path, optional key path for PEM files, passphraseSet for PKCS#12 bundles, or an error when configuration is invalid, and human-readable source labels), binaries, cache directories, integrations, MCP configuration flags, an mcpRuntime object when a configured MCP server was checked, Antigravity secrets hook flags (configured and valid under hooks when applicable), a vortex object, a top-level healthy boolean, and a recommendations array. mcpRuntime is null when no configured MCP server was checked, or when SONARQUBE_CLI_MCP_WSL is invalid on Windows. See Check the MCP container runtime. When MCP container networking guidance applies, that array includes a string that starts with MCP container networking:. Token state in JSON uses not_set, active, invalid, or set_unverified. When token verification fails because the server is unreachable, the authentication object may also include tokenError with the underlying network or TLS message.
The vortex object is { "applicable": false } when Vortex status does not apply (for example, SonarQube Server before 2026.5 Enterprise, or SonarQube Cloud without a resolved organization). When applicable, it includes applicable: true, a status of enabled, over_consumption, not_entitled, check_failed, or organization_not_accessible, and a consumption object with consumed and limit only on SonarQube Cloud while you're actively entitled.
When to use it
After
sonar auth loginor when integrations stop working: confirm the token, network settings, MCP config, container runtime, Vortex entitlement, and (for Antigravity) secrets hook are healthyBefore filing a support request: capture the status output
In CI diagnostics when the CLI behaves unexpectedly but commands still run
Related pages
Last updated
Was this helpful?

