Troubleshooting
Find the page that explains the message you see, from a deployment that does not start to a cluster that does not connect and a control plane that does not sign you in.
Each troubleshooting page lists messages by their text, with the cause, the fix and how to verify it; choose the area that matches what you see.
Find your area
| You see | Go to |
|---|---|
| A deployment that is refused, waits, stalls or fails: Waiting for approval, Blocked on a blocker, a toast that says it did not deploy | Deployments |
| A build that fails, never starts or builds the wrong way | Builds |
| A cluster that stays Awaiting agent, an agent that is offline, an install step that fails, a node that cannot join | Clusters and agents |
| A sign-in that is refused, an API call that answers 403 or 500, a control plane that does not start, an update that rolled back | Control plane |
| A database that does not become healthy, a restore that fails, a query that is refused | Databases |
Where messages appear
| Place | What it shows |
|---|---|
| The deployment's details in the console | The deployment's state, its blocker and its message. See Deployment states. |
| An error toast or the text beside a field | The detail of the API's answer to the request that failed. |
| Runtime output and the logs | What your processes wrote, and the cluster's events. See Logs and metrics. |
The detail field of an API error | The same sentence the console shows. See HTTP API. |
What to include in a report
- The installed version: Updates in Settings shows it, and
nebula versionprints it on the control plane host. The changelog says what each release changed. - The full message. The
detailof a 500 carries a request id; include it. - Whether Limits explains a request refused for its size or count.
Related
Audit log
The audit events NebulaCtrl records, their fields, how to filter and export them from the Activity page or the API, and what is never written to them.
Deployments
Find the message a refused, waiting, failed or stalled deployment shows, and fix its cause: approvals, deploy order, freezes, capacity, image pulls, startup and readiness.