Troubleshoot and diagnose

The appliance can describe its own state: which hypervisor it runs on, how much memory is left, which containers have been killed, whether the certificate is about to expire, whether anything can get out to a provider. Troubleshooting starts by reading that description, not by running commands and interpreting output.

The problem this guide solves

A support call that starts with "run docker ps, now show me the logs, now check whether 443 is listening" spends its first forty minutes collecting facts. Every one of those facts is already in the diagnostic snapshot, collected in about three seconds, in a form both this documentation and the in-product help assistant read.

How to troubleshoot

1. Collect the diagnostic snapshot. Call GET /admin/diagnostics/snapshot as an administrator; the in-product help panel reads the same document. The response ends with a findings list: rules the appliance evaluated over its own state. Each finding is one sentence naming the concrete thing that is wrong, and each names the runbook that fixes it.
2. Collect the support bundle before you change anything. The bundle is the snapshot plus the effective configuration with secrets redacted and the host agent's own status documents. It lets someone else diagnose the state you were actually in, rather than the state you left behind after three attempts at a fix.
3. Work the highest-severity finding first. Critical means the product is not serving or is about to stop; warning means it works now and will not keep working, or a control is not doing what you believe; info means it is worth knowing and needs no action today. One critical finding often explains several warnings — a host with no memory left produces one root cause and four symptoms.
4. Open the runbook the finding names. Every finding carries a runbook id, and every runbook is listed on the guided runbooks page. The runbook states the symptom in the words you would use, checks the appliance's own state in order, and names both the cause and the fix.
5. Run the runbook's verify step, then collect the snapshot again. A fix that removes the finding is done. A fix that leaves it in place was not the fix.

When there is no finding

A rule fires on a value, never on the absence of one. A deployment with no host agent reports no host findings rather than four criticals it cannot act on, so an empty findings list means either that nothing is wrong or that the thing that is wrong could not be measured. Read the diagnostic snapshot reference to see which sections are filled on your deployment before concluding the appliance is healthy.

When nothing fires and the product still misbehaves, start from the symptom:

How the runbooks work

A runbook is a machine-readable file, not prose. It lists the symptoms in the words you would type, the preconditions that establish you are in the right place, an ordered set of checks, and for each failing check the cause, the fix and a verification.

The same runbook therefore works three ways: as a checklist you read here, as an interactive checklist in the appliance's own copy of this documentation, and as something the in-product help assistant executes for you — running the checks it can and asking you only about what no tool can see. It works with no model configured and with no internet connection.

Limits and known gaps

• The snapshot cannot see the host by itself. The gateway container has no access to the Docker socket and no view of the machine: /proc/meminfo inside a container is the host's only by accident, and the disks it sees are its own overlay. The host and container sections come from a small agent that writes two files the gateway reads. Where that agent has never run, both sections are absent rather than wrong.
• Host facts are up to five minutes old, and are dropped entirely past thirty minutes. Reporting free memory that was true this morning is worse than reporting nothing.
• Findings are rules, not diagnosis. They name what is measurably wrong. A product that is behaving strangely with every rule passing needs the runbooks and the support bundle.
• Install-time failures happen before any of this exists. Nothing is collected until the product runs, so the installer's own console messages and /var/log/cid-firstboot.log are the evidence for anything that fails during provisioning.

Related

• Diagnostic snapshot — every key, what fills it, and how to send a bundle to support.
• Health matrix — every service, what breaks while it is down, and which finding fires.
• Guided runbooks — the full catalogue, grouped by lifecycle phase.