Troubleshooting

Diagnose deployment problems with the SonarQube Server AI agents, from unreachable components to jobs that fail or never start. This page is for SonarQube Server 2026.5.

Start with the health of the components, then narrow down by where the job stops. See Verifying the deployment for the checks themselves.

The AI Capabilities page says the agent isn't reachable

The agent is licensed and enabled, but SonarQube Server cannot reach the components. Work through these in order:

1. Confirm the Agent Orchestrator is running.
2. Confirm SonarQube Server has the right address for it. On a Docker Compose deployment, set it yourself with SONAR_HUNTERAGENT_ORCHESTRATOR_URL and SONAR_REMEDIATIONAGENT_ORCHESTRATOR_URL. See Configuration reference.
3. Confirm the network path allows SonarQube Server to reach the Orchestrator on its port.
4. Check the Orchestrator's own logs for a startup failure, particularly a database or storage connection error.

On Kubernetes, the Helm chart sets these addresses for you. If they're wrong, the usual cause is that the Orchestrator was enabled without the database override the chart needs, so it never started.

Jobs are accepted but never start

The job appears on the Agentic tasks page but no runtime container starts, or a container starts and exits immediately.

This is almost always the sandbox runtime. Sandbox selection is fail-closed, so an unsandboxed container is never used as a fallback.

Symptom	Cause	Fix
The container won't create, reporting an unknown runtime	runsc isn't registered on the host or node	Install and register the sandbox runtime, see Setting up the sandbox runtime
The container crashes on start with exec format error	The image architecture doesn't match the host, and the sandbox cannot run under emulation	Run the image on a host of the matching architecture
The pod won't schedule	No node carries the gVisor label, or the RuntimeClass is missing	Check the node labels and that the sandbox templates rendered
The pod reports that the runtime handler cannot be found	The cluster can't load the sandbox runtime, which is the expected result on OpenShift	See OpenShift

If a second SonarQube Server release in the same cluster fails to install, check runtimeClassName. A RuntimeClass is cluster-scoped, so the name must be unique per release.

Jobs fail early, while reading or writing files

The job starts but fails before doing any real work.

Cause	Fix
The runtime cannot reach the storage endpoint	Add the storage endpoint to the runtime's allowed outbound destinations. This is the most common cause on Kubernetes: turning on a network policy without a rule covering storage blocks every job at the first download
Path-style addressing is set incorrectly	Most S3-compatible endpoints need it enabled, Amazon S3 needs it disabled
Credentials are missing or wrong	Check the secret the Orchestrator and the runtimes read their storage credentials from
Storage is full	Free space and set a retention policy, see Setting a retention policy
The Orchestrator and the runtimes point at different locations	Both must use the same bucket or volume

Jobs fail with a configuration error

The runtime starts and exits with a configuration error rather than doing work. Check that an LLM provider and a model are saved under Administration > Configuration > AI Capabilities > LLM Providers, and that the runtime can reach the provider.

Outbound access to the LLM provider is a common miss when a network policy is enabled. Include the provider's address range.

If jobs fail with "AI service is unavailable" even though the provider passes Test connection, check the agent egress proxy. The runtime reaches the provider over its own network path, not SonarQube Server's, so passing Test connection does not mean the runtime can also reach it. Confirm the egress proxy allows the provider's address and port, see Network egress on Kubernetes or Network isolation on Docker Compose.

Jobs time out

The Orchestrator fails a job that runs longer than its time limit. Before raising the limit, check whether the job is actually progressing: a job that stalls immediately is usually blocked on network access rather than working slowly.

If jobs are genuinely being cut short on large repositories, raise the Orchestrator's job timeout, see Configuration reference.

Scheduled runs don't happen

Manual runs work but scheduled ones don't:

• The Orchestrator's scheduler must be enabled. It's off by default
• For the Hunter Agent, check the scheduler settings on SonarQube Server too
• For the Remediation Agent, check whether a run was skipped because the open pull request limit was reached. The agent resumes on its own once enough of its pull requests are merged or closed

Fixes aren't verified

The Remediation Agent opens pull requests, but SonarQube Server warns that fixes aren't being verified. Vortex analysis is unreachable. See Vortex analysis.

Errors from Vortex analysis appear in the SonarQube Server web.log, not in the per-job agent logs.

Vortex analysis runs without full context on large projects

Vortex analysis needs the analyzer context the scanner uploads during CI analysis. For a large project, that upload can exceed the default body-size limit of a reverse proxy or gateway in front of SonarQube Server. The scanner logs an HTTP 413 for the rejected upload but treats it as non-fatal, so analysis still succeeds, the context is simply missing, and later Vortex analysis calls, and the Remediation Agent's verification of its own fixes, lose precision.

Confirm your reverse proxy or ingress allows a request body large enough for your largest projects' analyzer context. Check the scanner's own execution log for the HTTP 413 on the context upload — the analysis run itself won't report a failure. See Reverse proxy body size.

The agent isn't available for a project

Deployment is fine, but an individual project can't use the agent. The most common reasons are that the project isn't bound to a repository, the agent lacks write access to that repository, or the project hasn't been analyzed.

The project's own settings page explains which of these applies. See Remediation Agent.

Gathering information for support

Collect these before you open a ticket:

• The Support Info File, which includes the component health and configuration
• The log for a failed job, downloaded from the Agentic tasks page
• The container logs for the Orchestrator and the runtime, read from your platform

Container logs that aren't tied to a specific job aren't available through SonarQube Server, and the log level of the agent components cannot be changed from the UI. Read them from your platform directly.

Next step

This page is a reference, not a step in the deployment itself. For the full sequence, see the Deployment roadmap.

Related pages

• Verifying the deployment

• Before you start

• Setting up the sandbox runtime