🔧 EZMON Troubleshooting

🔑 One-Time Registration Token Expired (401 Unauthorized)

Symptom: The install.sh script fails to register an agent with a 401 Unauthorized or Invalid registration token error.

Cause:

• Temporary reg_... registration tokens have a 5-minute TTL for security purposes. The token expires after 5 minutes or upon single-use.

Solution:

1. Open EZMON Dashboard → Agents → Add Agent (or click Update Agent).
2. Copy the newly generated reg_... token.
3. Re-run install.sh on your server host within 5 minutes.

⚙️ Evaluator Cron Failing (401 Unauthorized / HTTP 403)

Symptom: Cron jobs on cron-job.org or Upstash QStash return an HTTP 401 Unauthorized response code.

Cause: The Authorization header provided by your Cron worker does not match the CRON_SECRET environment variable configured on your Vercel Hub.

Solution:

1. Go to Vercel Dashboard → Project Settings → Environment Variables.
2. Verify the CRON_SECRET variable is present and set.
3. In cron-job.org or Upstash QStash, set HTTP Header:
   • Header Key: Authorization (or Upstash-Forward-Authorization in QStash)
   • Header Value: Bearer <YOUR_CRON_SECRET_VALUE>

🛡️ SHA-256 Checksum Mismatch During Install

Symptom: The install.sh installer aborts execution with FATAL: Checksum verification failed.

Cause: Incomplete binary download due to network interruption or stale GitHub Releases CDN cache.

Solution:

# Remove temporary downloaded files
rm -rf /tmp/ezmon-agent*
 
# Re-run installer script
curl -fsSL https://ezmon.web.id/install.sh | bash

✉️ Registration Email OTP Not Received

Symptom: New users do not receive the 6-digit email verification code during registration.

Solution:

1. Check your email Spam / Junk folder.
2. Verify that SMTP environment variables (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM) are correctly configured in Vercel Dashboard.

💻 203/EXEC Error on systemd

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

Solution:

# 1. Ensure binary exists and is executable
ls -la /usr/local/bin/ezmon-agent
sudo chmod +x /usr/local/bin/ezmon-agent
 
# 2. Test manual execution
EZMON_SERVER_URL=https://your-hub.vercel.app \
EZMON_AGENT_TOKEN=your-token \
/usr/local/bin/ezmon-agent
 
# 3. Reload and restart daemon
sudo systemctl daemon-reload
sudo systemctl restart ezmon-agent

🚨 Agent Persistently Offline / Heartbeat Missed

Symptom: Agent process is active, but dashboard status remains Offline.

Solution:

# 1. Check systemd unit status
systemctl status ezmon-agent
 
# 2. Stream agent logs
journalctl -u ezmon-agent -f
 
# 3. Verify EZMON_SERVER_URL does not include trailing slash
# Correct:    https://your-hub.vercel.app
# Incorrect:  https://your-hub.vercel.app/