Troubleshooting

systemd 203/EXEC Error

Symptom: ezmon-agent.service: Control process exited with error code 203/EXEC

Common causes:

Wrong ExecStart path in the service file
Binary missing execute permission
Binary is dynamically linked (requires specific glibc version)

Fix:


# 1. Verify the binary exists and is executable
ls -la /usr/local/bin/ezmon-agent
chmod +x /usr/local/bin/ezmon-agent
 
# 2. Test running it directly (bypass systemd)
EZMON_SERVER_URL=https://your-hub.vercel.app \
EZMON_AGENT_TOKEN=your-token \
/usr/local/bin/ezmon-agent
 
# 3. Confirm it's statically linked (must NOT show "dynamically linked")
file /usr/local/bin/ezmon-agent
 
# 4. Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart ezmon-agent

EZMON agent binaries from GitHub Releases are compiled with CGO_ENABLED=0 (fully static). If you compiled manually, ensure you use the same flag.

Agent Always Offline

Symptom: Agent is running but shows as Offline in the dashboard.

Diagnostic checklist:


# 1. Confirm agent is running
systemctl status ezmon-agent
 
# 2. View live logs
journalctl -u ezmon-agent -f
 
# 3. Manually test heartbeat
curl -v https://your-hub.vercel.app/api/agent/heartbeat \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"YOUR_AGENT_ID","heartbeatIntervalSec":30,"graceMultiplier":3}'
 
# 4. Check EZMON_SERVER_URL (no trailing slash!)
echo $EZMON_SERVER_URL
# Correct:  https://your-hub.vercel.app
# Wrong:    https://your-hub.vercel.app/

Metrics Not Showing

Ensure you’re using agent v0.1.1+ (earlier versions sent placeholder metrics)
Check logs for errors from /api/agent/metrics
Verify binary version: ezmon-agent --version

Notifications Not Sent

Telegram:

Ensure botToken format is correct: 123456:ABC-DEF...
Group chat IDs use negative numbers: -1001234567890
The bot must be added to the group with send message permission

Discord:

Verify the webhook URL is valid and the channel still exists


# Test Discord webhook manually
curl -X POST YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"content": "Test from EZMON"}'

Check Settings → Alert Channels in the dashboard for the alert_events audit log — it shows sent/failed status for every notification attempt.

Token Invalid / 401 Unauthorized

Each token is scoped to one agent only — ensure EZMON_AGENT_TOKEN matches the registered agent
Tokens cannot be used across projects
If lost: delete the agent from the dashboard and register a new one to get a fresh token

Cloud Monitor Always Failing

HTTP: Ensure URL uses HTTPS and expectedStatus matches the actual response code
TLS: Uses crt.sh for lookup — domain must be publicly resolvable
Keyword: Case-sensitive — ensure the keyword exactly matches page content

Database / Migration Errors


# Re-run migrations
npm run --prefix packages/db migrate
 
# Generate new migration after schema changes
npm run --prefix packages/db generate
 
# Verify DATABASE_URL is set
echo $DATABASE_URL