> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/troubleshooting.md).

# 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](/sonarqube-server/server-installation/ai-agents/verifying-the-deployment.md) for the checks themselves.

## The AI Capabilities page says the agent isn't reachable <a href="#agent-not-reachable" id="agent-not-reachable"></a>

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](/sonarqube-server/server-installation/ai-agents/configuration-reference.md).
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.

{% hint style="info" %}
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.
{% endhint %}

## Jobs are accepted but never start <a href="#jobs-never-start" id="jobs-never-start"></a>

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](/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md)                                                                                                              |
| 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                                                                                                                                                                                                   |
| On OpenShift, the chart fails to install with `The RuntimeClass "kata" does not exist in this cluster.`                                             | The Kata `RuntimeClass` is missing, because the OpenShift sandboxed containers operator is not installed                                        | Install the operator, see [Setting up the sandbox runtime](/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md#on-openshift)                                                                                                                     |
| On OpenShift, the chart fails to install with a `forbidden` error from the API server                                                               | The installing credentials cannot read cluster-scoped `RuntimeClass` objects, so the chart cannot check that the Kata `RuntimeClass` exists     | Grant the installing credentials read access to `RuntimeClass` objects, or set `OpenShift.skipAgentRuntimeClassCheck` to `true`, see [Setting up the sandbox runtime](/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md#openshift-helm-values) |
| On OpenShift, the agent runtime Deployments stay at 0 available, and the ReplicaSet events show `FailedCreate` with `RuntimeClass "kata" not found` | The Kata `RuntimeClass` is missing, and `OpenShift.skipAgentRuntimeClassCheck` is set to `true`, so the chart installed without checking for it | Run `kubectl get runtimeclass kata` to confirm that the `RuntimeClass` is missing, then install the operator, see [Setting up the sandbox runtime](/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md#on-openshift)                             |
| On OpenShift, the pod reports that the runtime handler cannot be found                                                                              | The `RuntimeClass` exists, but the node the pod is scheduled on has no matching Kata handler                                                    | Check that the OpenShift sandboxed containers operator has set up Kata Containers on that node, see the [OpenShift sandboxed containers documentation](https://docs.redhat.com/en/documentation/openshift_sandboxed_containers/)                                |

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 <a href="#storage-failures" id="storage-failures"></a>

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 up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md#retention)                                                                      |
| The Orchestrator and the runtimes point at different locations | Both must use the same bucket or volume                                                                                                                                                                                  |

## Jobs fail with a configuration error <a href="#configuration-errors" id="configuration-errors"></a>

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](https://github.com/SonarSource/helm-chart-sonarqube/tree/master/charts/sonarqube#network-egress) on Kubernetes or [Deploying with Docker Compose](/sonarqube-server/server-installation/ai-agents/deploying-with-docker-compose.md#network-isolation) on Docker Compose.

## Jobs time out <a href="#timeouts" id="timeouts"></a>

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](/sonarqube-server/server-installation/ai-agents/configuration-reference.md).

## Scheduled runs don't happen <a href="#scheduled-runs" id="scheduled-runs"></a>

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 <a href="#fixes-not-verified" id="fixes-not-verified"></a>

The Remediation Agent opens pull requests, but SonarQube Server warns that fixes aren't being verified. Vortex analysis is unreachable. See [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#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 <a href="#context-upload-limits" id="context-upload-limits"></a>

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 [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#reverse-proxy-body-size).

## The agent isn't available for a project <a href="#project-unavailable" id="project-unavailable"></a>

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](/sonarqube-server/project-administration/ai-features/remediation-agent.md).

## Gathering information for support <a href="#support-information" id="support-information"></a>

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

{% hint style="info" %}
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.
{% endhint %}

## Next step <a href="#next-step" id="next-step"></a>

This page is a reference, not a step in the deployment itself. For the full sequence, see the [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#roadmap).

## Related pages <a href="#related-pages" id="related-pages"></a>

* [Verifying the deployment](/sonarqube-server/server-installation/ai-agents/verifying-the-deployment.md)
* [Before you start](/sonarqube-server/server-installation/ai-agents/before-you-start.md)
* [Setting up the sandbox runtime](/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.