Skip to the content
WellKept

// Help

Troubleshooting

A server that never appears, goes offline or reports something you did not expect.

A server never appears#

Start on the server.

systemctl status wellkept-agent
journalctl -u wellkept-agent -n 50 --no-pager
  • "Enrolment failed" with an invalid enrolment token. The command works once and expires after an hour. Create a new one under Add a server. If you ran it twice, the second run was refused, and a new command is the fix.
  • A 402 at install, or "server limit". The plan is full. Remove or revoke a server, or change the plan, then try again. Plans and billing explains what counts.
  • A connection or certificate error. The server needs outbound HTTPS on port 443 to WellKept. Check with curl -I https://wellkept.fullwerks.co.uk/install.sh from the server. If it sits behind a proxy, set HTTPS_PROXY for the service in a systemd drop-in.
  • "Ed25519 signature does not verify; refusing to install." Do not work around it. The download was changed or cut short. Run the command again. If it keeps failing, write to us.
  • The service is running, and the page still says waiting. The first heartbeat arrives within a minute. If the server has enrolled but not reported after five, read the journal for the agent's own words. API errors are logged with their title and detail.

A server shows as offline#

WellKept marks a server offline after three missed heartbeats, about three minutes.

  1. Is the server up? Check from somewhere else.
  2. Is the service running? systemctl status wellkept-agent.
  3. Can it reach WellKept? Look for connection errors in journalctl -u wellkept-agent.
  4. Did the server's clock jump? The agent reports a drift of more than five minutes as its own finding.

If the agent logged that the server was revoked or removed, it stopped on purpose and will stay stopped. Add the server again.

A finding is wrong, or will not clear#

  • Press Re-check now and wait a minute. A finding clears on the first report in which it is no longer true.
  • A finding about pending updates can take up to an hour to clear after you upgrade, because the agent refreshes its own package lists hourly. To use the system's lists instead, set apt_refresh_interval = 0 in /etc/wellkept/agent.conf, and restart the service. What the agent reads says what that costs.
  • A section is missing. If a probe failed, the report lists it as a probe error and WellKept skips the rules that read it. Run sudo -u wellkept wellkept-agent collect to see which, and why.
  • No WordPress or Laravel version for a site under /home. The agent cannot enter that directory. Installing the agent has the two fixes.
  • A service reported as public that is not. Check what it listens on with sudo ss -ltnp. An address of 0.0.0.0 or :: means every interface. Bind it to 127.0.0.1 and re-check. The finding's playbook has the exact lines for each service.
  • You resolved a finding and it came back. It was still true. That is how WellKept tells you.

An alert did not arrive#

  • Is the channel verified? A channel is sent real alerts only after its test message got through. Save it again, or use the test button.
  • Does its rule include that event and that severity? Low severity is held for the digest. A medium one inside quiet hours is held too.
  • Look at History on the Alerts page. It shows every alert as sent, held or failed, with the reason.
  • For email, check the member is ticked on the channel, and check the spam folder.
  • For a webhook, your address must answer with a 2xx within 10 seconds. The History row shows what it did answer.

A monitor says the site is down and it is not#

  • The check fetches the URL like a browser, with a timeout you set. A slow page can fail it. Raise the timeout, up to 30 seconds.
  • A certificate that does not verify fails an HTTP check. Browsers sometimes forgive this where a monitor does not.
  • A firewall or a bot-protection rule may block WellKept-Monitor/1.0. Allow it.
  • The healthy status range is 200 to 299 unless you changed it. A page that redirects to a login with a 200 is up, and one that answers 403 is not.

Anything else#

Write to hello@fullwerks.co.uk with the server's name and what the journal says. Do not include a token. A token starts wk_srv_ or wk_enrol_, and nobody at WellKept will ever ask you for one.