Troubleshooting

Answers to the most common problems. If yours isn't here, contact support with the server name and what you've tried.

The server stays on "Waiting for agent"#

1. Check the service is running:

   systemctl status alertly-agent
   

2. Read its recent log lines. Errors are written in plain language:

   journalctl -u alertly-agent -n 50 --no-pager
   

3. Common causes:

   • "the agent token was rejected": the token was replaced or mistyped. Open the server's Settings, choose Generate new token, and run the new command.
   • Connection timed out: a firewall blocks outbound HTTPS. Allow the server to reach https://alertly.net/api/v1 on port 443.
   • Certificate errors: the server's clock is wrong, or the CA bundle is outdated. Run timedatectl and update the ca-certificates package.

The server shows as offline, but it's up#

A server is offline when no report arrives for three reporting intervals. Check the agent as above. Network hiccups resolve on their own, and the alert clears with the next report. If the server was rebooted, the agent starts again automatically with systemd.

The installer fails#

• "systemd is required.": the agent runs as a systemd service. Containers and some minimal images don't run it. Install the agent on the host instead.
• "Unsupported architecture": only amd64, arm64 and armv7 are supported.
• "Checksum verification failed": the download was interrupted. Run the command again.
• "--docker was given but this server has no docker group": install Docker first, or leave out --docker.
• "This installer must be run as root": run it with sudo, as in the copied command.
• "A valid agent token is required": copy the whole command. Tokens look like alr_ followed by 48 letters and numbers.
• "Could not download": the server can't reach GitHub. See Behind a proxy or firewall.
• "The agent service failed to start": run journalctl -u alertly-agent -n 50 to see why.

Containers aren't listed#

Run the install command again with --docker, plus any other options you used. The agent needs the Docker socket, which is only granted when you ask for it. If the page says the agent can't reach Docker, check that Docker is running. If containers still don't appear, your Alertly.Net administrator may have turned off Docker data.

I'm not receiving alerts#

1. Open Channels and use Send test on each one. An error tells you what the service rejected.
2. Check the channel is enabled, and not inside its quiet hours.
3. Check whether a maintenance window is running, or the server, monitor or heartbeat is paused.
4. For rules: check the duration. A rule "for 10 minutes" only fires after 10 minutes of the condition holding.
5. For email: look in spam, and add our sending address to your contacts.

I'm getting too many alerts#

• Raise thresholds, or lengthen durations, so short spikes don't count.
• Add a server-specific rule for busy machines.
• Add quiet hours to noisy channels, and keep critical alerts allowed through.
• Use escalation channels for phones, so they only ring when nobody responds.

An uptime monitor says down, but the site works#

• Look at the error on the monitor page: a timeout, an unexpected status code or a missing keyword.
• Your firewall or CDN may block our checks. Allow the Alertly-Monitor/1.0 user agent.
• If the site is slow, increase the timeout.

A heartbeat says missed, but the job ran#

• Make sure the ping runs after the job, and that curl is installed where the job runs.
• Check the period and grace time match the real schedule. For cron schedules, check the timezone.
• Try the ping URL by hand. The heartbeat page shows every ping received.

Two-factor authentication: lost phone#

Sign in with one of your recovery codes instead of a code from the app. Then turn two-factor off and on again in Profile to connect your new phone. No recovery codes? Contact support from the email address on the account.