Skip to main content

wakora doctor, line by line

sudo wakora doctor

The checks run in dependency order and each one assumes the previous passed, so the first FAIL is the problem; everything below it is a consequence. Each failing line prints a "next" hint; this page is the long version of those hints. For a support request, wakora doctor --bundle writes a redacted archive to the temp directory (no secrets, the same redaction the agent applies to everything).

Every line ends in one of OK, WARN, FAIL, INFO or SKIP. INFO is context, not a verdict; SKIP means the check had nothing to measure against (usually because an earlier one failed).

agent​

The binary and its version. FAIL only when the binary cannot describe itself, which means a corrupted or partial download: reinstall with the one-line installer, which verifies the file before writing it.

service​

Whether the agent service is installed and running under the platform's service manager (systemd, OpenRC, sysvinit, launchd, the Windows Service Control Manager).

  • WARN service not installed: the binary is there but nothing keeps it running. The line names the command for this host's init system (systemctl start wakora-agent, rc-service wakora-agent start, and so on). On systemd hosts the installer writes the unit; on OpenRC or sysvinit copy the script from the public repository (see the Alpine and Debian pages); on Windows run wakora service install from an elevated prompt.
  • WARN cannot query the service manager: run doctor as root or Administrator.
  • The line also warns when the service is installed but not running; start it and read the agent log for the reason it stopped.

disk​

The state directory (/var/lib/wakora, or %ProgramData%\Wakora) must be writable and have room for the offline spool.

  • FAIL not writable: permissions or a read-only mount; the agent cannot spool, stage or record status there.
  • WARN on low free space: the spool is bounded, but a full disk also stops the log and the identity rewrite on key rotation. Free space or move the directory.

identity​

Whether the host is registered.

  • WARN not registered: wakora --key never succeeded here. The service idles and starts collecting the moment you run it. If registration failed at install time, the key is parked encrypted and retried on its own; see First start.
  • WARN present but this user cannot read it: run doctor as root.
  • FAIL sealed to this machine and no longer decryptable: the identity file came from another machine (a cloned image, a restored backup) or the machine id or the root-only seed changed since. The identity is bound to the machine on purpose. Re-register: sudo wakora --key <YOUR_TEAM_KEY>; the old file is kept aside as identity.undecryptable-<time>.
  • FAIL this host is a copy of server <uuid>: the platform found this machine running alongside the original under one identity and refused to register it as a new host (the reason follows, usually the plan's host limit). The identity was moved aside as identity.copy-<time>; wakora --key registers the machine once there is room. See Two machines, one identity.
  • WARN N of M sealed on another machine: local secrets were stored on a different machine (or before a machine id change) and cannot be read here. The probes that need them say so instead of "not set". Store them again with wakora secret set.

dns​

The endpoint name built into the binary must resolve.

  • FAIL does not resolve: the host's resolver cannot answer for eu.gw.wakora.io. Check /etc/resolv.conf, a split-horizon zone that shadows wakora.io, or an egress policy that blocks DNS. Nothing on the agent side to configure; the name is baked in.

tcp 8443​

A TCP connection to the endpoint on port 8443.

  • FAIL cannot connect: outbound 8443 is blocked, or the route is wrong. The agent needs exactly one outbound TCP port and nothing inbound; see Connectivity for what to ask your network team.

tls​

A TLS handshake, then a comparison of the server's public key with the pin built into the binary.

  • FAIL handshake failed: something terminates TLS before our endpoint, or the connection is being reset mid-handshake.
  • FAIL server key does not match the pinned key: a TLS-inspecting proxy or firewall re-signs the connection with its own certificate. The pin fails by design; the agent will not talk through an interception point. Ask for the endpoint to be exempted from inspection. See Restricted networks.
  • INFO no pin built in (dev build): a locally built binary; published builds always carry a pin.

clock​

The host clock against the time the endpoint reports.

  • WARN on drift of a few minutes: timestamps on the data are still corrected on arrival, but log lines and traces from this host sort wrong against other hosts. Enable NTP (chronyd, systemd-timesyncd, w32tm).
  • FAIL on large drift: TLS itself may fail once certificates appear not yet valid or expired from this host's point of view. Fix the clock first, then re-run.

auth​

Whether the running agent holds an authenticated connection, read from the status the agent writes.

  • WARN the agent is not connected right now or last connection error: read the log for the reason; usually a network condition the checks above already named.
  • WARN this host was removed from the console (410): someone removed this host in the console. The agent is idle on purpose and keeps its identity. To monitor the host again, register it anew with wakora --key; it comes back as a new host.
  • FAIL rejected the per-server key (401): the host's own key is no longer valid. This happens after the identity was copied to a second machine (the twin rotated the key), or after a restore from an old backup. Re-register with wakora --key.
  • FAIL retired-key: the key this host holds was already replaced; the host was restored from a snapshot or backup older than its last key rotation. The platform refuses it on purpose (an old backup must not take over the live host). Re-register with wakora --key.
  • INFO not reported by the running agent: the service has not started yet, or runs an older build that does not write status; start it or update.

data flow​

Whether the platform acknowledged data recently.

  • WARN connected, no delivery acked yet: normal in the first seconds after a start.
  • WARN with an age: the connection is up but nothing has been acknowledged for a while. If it persists, the log shows write errors; the agent spools meanwhile and replays when the acknowledgements resume, so nothing is lost.

Everything is OK but the host is not in the console​

Then the agent is fine and the question is which workspace it registered to: the team key decides. See The host does not appear.