--- title: Check error reference description: Every failure code a Glowo check can report, what it means, and what to do about it. sidebar: label: Check errors --- {/* Source of truth: packages/shared/src/check-errors.ts — CheckErrorCodes and CheckErrorMessages. The tables below are transcribed from that file; if you add a code there, add it here. */} When a check fails, the heartbeat records a code explaining why. This page lists all 36 of them. The codes fall into two families, and telling them apart saves a lot of time: - **Configuration errors** mean the monitor is wrong. Glowo never even got to make the request. Fix the monitor. - **Everything else** means the request happened and something went wrong. Fix the service, the network, or the certificate. ## Configuration | Code | What it means | | --- | --- | | `INVALID_CONFIG` | The monitor configuration is malformed and could not be parsed. Please review the monitor settings. | | `INVALID_SCHEME` | The monitor URL uses a scheme that is not allowed. Only http, https, ws, and wss are supported. | | `MISSING_URL` | No URL was provided for this monitor. A valid URL is required to perform the check. | | `MISSING_HOST` | No hostname was provided for this monitor. A valid host is required to perform the check. | | `MISSING_PORT` | No port was specified for this monitor. A valid port number is required for TCP connections. | | `TARGET_BLOCKED` | The target resolves to a private, loopback, or cloud-metadata address. Public hosts only — internal targets are blocked for security. | | `PAYLOAD_TOO_LARGE` | The configured request body exceeds the 1 MiB limit. Reduce the body size or split the payload. | ## Network and connection | Code | What it means | | --- | --- | | `CONNECTION_CLOSED` | The remote server closed the connection before sending a complete response. This typically indicates the server dropped the connection unexpectedly. | | `CONNECTION_REFUSED` | The connection was actively refused by the target host. The server may be down, the port may be closed, or a firewall is blocking the request. | | `CONNECTION_TIMEOUT` | The connection attempt timed out before a response was received. The server may be unreachable or experiencing high latency. | | `REQUEST_TIMEOUT` | The request exceeded the configured timeout limit. The server took too long to respond. | | `REQUEST_CANCELED` | The check was cancelled before completing — typically because the checker is shutting down. The next run will retry. | | `DNS_LOOKUP_FAILED` | DNS resolution failed for the target hostname. The domain may not exist, or the DNS server is unreachable. | | `NETWORK_ERROR` | A network-level error occurred while attempting to reach the target. Check that the host is accessible and no infrastructure issues are present. | | `REDIRECT_LIMIT` | The request exceeded the maximum number of allowed redirects. This may indicate a redirect loop on the target server. | ## TLS | Code | What it means | | --- | --- | | `TLS_HANDSHAKE_FAILED` | The TLS/SSL handshake could not be completed. The server may not support HTTPS, or there is a protocol version mismatch. | | `TLS_CERT_ERROR` | The server's TLS certificate is invalid. It may be self-signed, expired, or issued for a different domain. | | `TLS_CERT_EXPIRED` | The server's TLS certificate has expired and is no longer valid. The certificate must be renewed. | | `TLS_NO_CERTIFICATES` | The server did not present any TLS certificates during the handshake. Verify that TLS is correctly configured on the target. | ## HTTP | Code | What it means | | --- | --- | | `REQUEST_BUILD_ERROR` | The HTTP request could not be constructed. The URL or request parameters may be malformed. | | `UNEXPECTED_STATUS` | The server returned an HTTP status code outside the expected range. Review the expected status codes in the monitor configuration. | | `BODY_MISMATCH` | The response body did not match the configured assertion. The expected content was not found in the response. | | `BODY_SCHEMA_MISMATCH` | The response body did not conform to the configured JSON Schema. The response structure differs from the expected schema. | ## DNS | Code | What it means | | --- | --- | | `DNS_UNSUPPORTED_TYPE` | The specified DNS record type is not supported. Use a standard type such as A, AAAA, CNAME, MX, TXT, NS, or SRV. | | `DNS_QUERY_FAILED` | The DNS query could not be executed. The nameserver may be unreachable or the query timed out. | | `DNS_RCODE_ERROR` | The DNS server returned an error response code. The domain may not exist (NXDOMAIN) or the server encountered an internal failure. | | `DNS_NO_RECORDS` | The DNS query succeeded but returned no records for the requested type. The record may not be configured on the domain. | | `DNS_VALUE_MISMATCH` | The DNS records returned do not match the expected value configured in the monitor. The DNS configuration may have changed. | ## WebSocket | Code | What it means | | --- | --- | | `WS_SEND_FAILED` | Failed to send a message over the WebSocket connection. The connection may have been interrupted after the handshake. | | `WS_RECV_FAILED` | Failed to receive a message from the WebSocket server. The server may not have responded, or the connection was dropped. | | `WS_MESSAGE_MISMATCH` | The WebSocket response did not contain the expected message content. The server may have returned unexpected data. | ## gRPC | Code | What it means | | --- | --- | | `GRPC_UNAVAILABLE` | The gRPC endpoint is unavailable. The server may be down, restarting, or unreachable over HTTP/2. | | `GRPC_HEALTH_NOT_SERVING` | The gRPC health service reported NOT_SERVING. The server is reachable but declares itself unhealthy. | | `GRPC_HEALTH_UNKNOWN_SERVICE` | The gRPC health service does not know the requested service name. Verify the service name, or leave it empty to check overall server health. | | `GRPC_HEALTH_UNIMPLEMENTED` | The server does not expose the standard gRPC health service (grpc.health.v1). Switch the monitor's check mode to connectivity to monitor this endpoint. | | `GRPC_ERROR` | The gRPC health check failed with an unexpected status. Review the detailed error message for the status code returned by the server. | ## Ping (ICMP) | Code | What it means | | --- | --- | | `ICMP_RESOLVE_FAILED` | Could not resolve the hostname to an IP address for the requested protocol version. Verify the host and IP version settings. | | `ICMP_LISTEN_FAILED` | Failed to open a socket for ICMP communication. Ensure the host kernel allows unprivileged ICMP (sysctl net.ipv4.ping_group_range). | | `ICMP_SEND_FAILED` | Failed to send the ICMP echo request packet. A network-level error prevented the packet from being transmitted. | | `ICMP_RECV_FAILED` | No ICMP echo reply was received within the timeout period. The host may be unreachable, or ICMP is blocked by a firewall. | ## Other | Code | What it means | | --- | --- | | `UNKNOWN_ERROR` | An unexpected error occurred during the check. Review the detailed error message for additional context. | ## The three you will actually see most **`TARGET_BLOCKED`** — the target resolved to a private, loopback, or cloud-metadata address. This is a deliberate security boundary, not a bug: Glowo will not be used to probe internal networks. To watch something that is only reachable privately, use a [push monitor](/monitors/push) driven from inside that network. **`TLS_CERT_EXPIRED`** — almost always an automated renewal that stopped working weeks ago and went unnoticed. Check the renewal job itself, not just the certificate. **`UNEXPECTED_STATUS`** — often the monitor is wrong rather than the service. An endpoint that legitimately returns `401` or `403` to an unauthenticated probe needs those codes listed in `expectedStatusCodes` on the [HTTP monitor](/monitors/http). ## Reading a failure properly 1. **Check whether all regions failed.** One region failing while seven succeed is a network path problem, not an outage. See [Regions](/monitors/regions). 2. **Open the heartbeat.** It carries the code, the message, and the timing breakdown — DNS, connect, TLS and total. 3. **Compare against the last success.** A latency cliff before the failure points at resource exhaustion; an instant failure points at something refusing connections.