Help
Troubleshooting
Common issues when installing agents, hitting quota, or debugging webhook delivery.
A monitor stays "pending" and never reports up/down
Checks run on the interval you configured — a brand-new monitor can take up to one full intervalSeconds before its first result lands. If it's been longer, verify the target is reachable from MonSPHERE's network (for self-hosted, from the monitoring-api container).
403 quota_exceeded when creating a resource
Your organization has hit its subscription plan's limit for that resource type (monitors, agents, or users). Check current usage at GET /organizations/:orgId/subscription, then upgrade the plan or remove unused resources.
Agent won't connect
Confirm the enrollment token hasn't expired and that the agent can reach agent-gateway's gRPC port (50051 by default) over mTLS — a corporate proxy or firewall silently dropping gRPC traffic is the most common cause in self-hosted deployments.
Webhook deliveries failing
Check the webhook_deliveries history for the specific webhook — each attempt (up to 3) is recorded with its response status. A non-2xx response, timeout, or TLS failure on your endpoint will show there. Verify you're checking the X-MonSPHERE-Signature header correctly — see Developer Center.