Troubleshooting

Start here, always:

systemctl status uptimecraft-agent
journalctl -u uptimecraft-agent -n 100 --no-pager

The agent says what it is doing, and it says why when it refuses to do something.

The install

openssl is required to verify the release signature — install it. The installer will not continue without being able to check the signature, and there is no way to tell it to. On a minimal image, also check for curl.

run this as root — it creates a system user and installs a unit file.

macOS support is partial and has no installer yet — correct. Linux with systemd only.

the release signature does not verify against any known UptimeCraft key — this is not a corrupted download; it means the checksum file was not signed by us. Do not install it, and please tell us. Check first that you fetched the script from https://dev.uptimecraft.com/install.sh and not from a copy or a mirror.

checksum mismatch — a truncated or interfered-with download. Nothing was installed. Retry; if it recurs, say so.

this installer needs systemd — there is no init-script packaging.

After installing

Nothing in Settings → Servers. The journal carries the reason we gave:

• "That enrollment token is not valid." The token is expired, revoked, out of uses, or mistyped. We do not say which on purpose — distinguishing them would let someone test tokens against us and learn something from the answer. Make a new one; the page shows each token's uses and expiry if you want to know which it was.
• "This plan allows N servers and N are already enrolled." Revoke a server you no longer run, or move up a plan.
• "This plan does not include server monitoring." Server monitoring is on the Business plan.
• A connection error rather than a message from us — outbound HTTPS to https://dev-api.uptimecraft.com is blocked. Test with curl -sS https://dev-api.uptimecraft.com/actuator/health from the machine.

Service restarting in a loop. Usually a token the agent cannot use. The journal says which. The agent exits rather than retrying in place, and systemd restarts it thirty seconds later, so a fixed token takes effect within half a minute — systemctl restart uptimecraft-agent if you do not want to wait.

Stuck on "Pending approval". Another machine has the same identity. Approve it if it is genuinely a separate server; if a whole batch is queueing up, the image was baked after enrolling — see Manage your servers.

The numbers

Memory looks higher than free -h suggests. We use MemAvailable, which is what the kernel believes it could actually give you. MemFree excludes the page cache and would report every healthy Linux server as nearly full.

A disk sits at 100% and is not a problem. It is a snap image — squashfs, always full by design. Automatic discovery excludes these. If you see one, you are probably in manual mode and selected it.

A monitored disk vanished from the machine. The check goes stale and any open incident stays open. An unmounted disk is not a fixed disk.

CPU reads lower than top does. iowait counts as idle here. A process blocked on a slow volume is not the CPU being busy, and counting it as usage reports a machine waiting on a disk as pinned.

Load looks small on a big machine. It is divided by core count, so 1.0 means fully busy on any machine. A raw load average means different things on two cores and on thirty-two, which makes it a number nobody can set a threshold against.

A check says "Not collected". The agent cannot do it — it is either not collected on this platform, or it needs a newer agent than the one installed. The page says which.

Gaps in the graph

One interval missing. A dropped report. The agent does not keep a backlog; the next report resumes.

Gaps in a pattern. The reports are not arriving. Check the journal for network errors, and check anything between the machine and us that might be rate-limiting.

Everything older than a point is gone. Retention. Raw samples are kept for a shorter window than the hourly summaries, which is what long graphs are drawn from.

Still stuck

Email support@uptimecraft.com. The useful things to send:

• the server's name in the dashboard;
• journalctl -u uptimecraft-agent -n 200 --no-pager;
• uptimecraft-agent --version;
• your distribution and uname -m.

The journal does not contain your enrollment token or the server's key, so you can send it as it is.