Troubleshooting and FAQ

A server shows offline

A server is marked offline when no heartbeat has arrived for 3 minutes. On the server, run systemctl status infrapilot-agent and journalctl -u infrapilot-agent -n 50. If the service is not running, sudo systemctl restart infrapilot-agent. If it is running but cannot reach the API, check that outbound HTTPS (port 443) to api.getopservo.com is allowed by your firewall or proxy. A 401 “Invalid signature” in the log means the credentials in /etc/infrapilot/config no longer match the server record; re-run the install command with OPSERVO_FORCE=1 to re-register.

Install says the enrollment token is invalid or expired

The install command from Add server works once and only for the next hour. If the dashboard shows “This enrollment expired before the server checked in”, or the installer gets “Invalid or expired enrollment token”, open Add server again to generate a fresh command and run that one.

A server with this identity already exists

The installer stops with “This server is already added to another Opservo workspace” and the Add server window you generated the command from shows Move it to this workspace or Leave it where it is. A server belongs to one workspace only, so Opservo asks rather than creating a duplicate. Moving needs an owner or admin.

The plan’s server limit was reached

On Free, a third install is refused with “This workspace’s Free plan allows up to 2 servers.” Archive a server you no longer need, or upgrade on Account → Billing, then run the install command again. See Plans, credits and billing.

The agent shows an “update” badge

The fleet grid flags a server whose agent is “An older agent build than we now serve”. Agents update themselves within an hour of a release, so it usually clears on its own; Update agent pulls the build now. If the badge says the agent is too old to be updated remotely, re-run the one-line install command on that server; it reuses the existing credentials and creates no duplicate. See Agent updates.

A health score category says “no data”

A category shows no data when the agent has not yet reported the facts that category needs, for example right after install or when a check is not applicable to that server. Each rule also carries a confidence label: Definitive, Likely or Heuristic. Wait for a couple of heartbeats; if it stays empty, open the category to see which facts are missing. See Health score.

Alerts are not arriving

Alerts are delivered only through notification channels; there is no automatic fallback to your email. If a workspace has open critical alerts and no channel at all, a red banner appears on the dashboard and workspace owners get a nudge email. Add a channel on Account → Notifications. If a channel exists, open it there: each shows its last delivery result, including Last delivery failed and the error text returned by the destination. Use Test after fixing it. Discord webhook URLs are recognised automatically when pasted as a Webhook channel. See Alerts and channels.

Run fix is refused

The refusal text says why. “Remote actions are turned off for this server. Enable them in the Actions tab first.”: flip the per-server switch on the server page. “Remote actions require a Growth plan or higher.”: upgrade the workspace. “The server didn’t respond in time — it may be offline, or its agent may need an update”: the agent must be heartbeating; see the offline section above. “Only an owner or admin can run a free-text command”: ask an admin or use the quick action. Details in Remote actions.

The fix fails because sudo asks for a password

Commands run non-interactively, so a sudo password prompt (“a password is required”) can never be answered, and each retry logs a new failed-auth event. Give the agent’s OS user a scoped passwordless grant for the one command, once, on the server:

echo '<user> ALL=(root) NOPASSWD: <command>' | sudo tee /etc/sudoers.d/opservo-actions && sudo chmod 440 /etc/sudoers.d/opservo-actions && sudo visudo -c

Use a specific command, not ALL. The security score ignores scoped entries in /etc/sudoers.d/opservo-actions but still flags a blanket NOPASSWD: ALL anywhere.

A terminal command expired or timed out

Terminal commands get up to 600 seconds. A command that runs longer is killed and shows as timed out; one the agent never picked up before its deadline shows as expired. For longer jobs, start them with nohup or in a tmux session and check the result with a second command. See Terminal.

AI actions say “Out of AI credits”

Your monthly allowance and any top-ups are used up. Monitoring continues; only AI features pause. Top up from the AI Wallet, connect your own AI key on Account → Developer, or wait for the reset on the first of the month. See Plans, credits and billing.

I am locked out after wrong PINs

Five wrong PINs sign you out on every device. Sign in again with your password (and 2FA code if enabled); you will then set a new PIN. Five wrong passwords lock the account for 15 minutes; use Forgot password? on the sign-in page if you are unsure of it. See Screen lock.

Still stuck?

Email hello@getopservo.com with the server name, what you clicked and the exact message you saw. For agent problems, include the last 50 lines of journalctl -u infrapilot-agent.