Troubleshoot Node Alerting

Diagnose Alert Delivery Issues for the Optional Alerting Extension in nodectl

Introduction

This guide provides a series of basic troubleshooting steps to help you resolve issues with the alerting module associated with the auto_restart feature in nodectl.

---

🚨 Support Disclaimer

Important

The alerting module is a community extension of nodectl and not officially supported.

Use at your own risk. Limited support is available, and advanced troubleshooting may not be provided.

---

🔁 Step 1: Clear the Alerting Cache

Start by clearing the alerting module’s internal cache:

sudo nodectl auto_restart clear_alerts

This resets any internal flags that may be preventing alert dispatch.

---

📬 Step 2: Send a Test Report

To test if the daily reporting mechanism works:

sudo nodectl auto_restart send_report

Check your inbox for the report. If not received, continue with the next steps.

---

📣 Step 3: Send a Test Alert

Trigger an alert manually:

sudo nodectl auto_restart alert_test

This simulates a node failure alert. Verify that the message is received by the configured email or SMS gateway.

---

🧾 Step 4: Review Logs

Check the nodectl logs for any errors related to alert dispatch:

sudo nodectl logs -l nodectl

Look for entries that may indicate connection failures, authentication errors, or message rejection.

---

📥 Step 5: Check Email Spam Filters

If alerts are routed to a standard email inbox:

• Check your Spam or Junk folders

• Add the configured sender (e.g., your Gmail alert account) to your email whitelist or safe senders list

• Create filter rules in your email settings to allow all mail from that address to reach your inbox

• Confirm your email provider hasn’t rate-limited or blacklisted your alerting Gmail account

---

📱 Step 6: Mobile SMS/MMS Alerting Considerations

If you’re routing alerts to a mobile number via email-to-SMS/MMS:

• ✅ Ensure MMS is supported and enabled on your phone

• ✅ Test sending a manual email to your mobile email address (e.g., [e-mail])

• ⚠️ Contact your mobile carrier and request approval to receive messages from your node’s Gmail address—some providers block automated or high-frequency alerts

• 🚫 Mobile providers may "black hole" repetitive or unauthenticated email messages to prevent spam

---

🆘 Step 7: Seek Help (Last Resort)

If you've exhausted all basic troubleshooting steps:

• Join the Constellation Network Official Discord

• Navigate to the appropriate validator support channel

• Provide details such as:

  • Your nodectl version

  • Email provider used for alerts

  • Mobile provider (if applicable)

  • Relevant error logs or symptoms